@terrascale/sdk 0.0.3 → 0.0.4

package/src/v1/management-routes.js

@@ -0,0 +1,67 @@
+/** @typedef {"getShapeManifest" | "healthz" | "readyz" | "backupz" | "replicationHealth" | "listPlatformDatabases" | "listPlatformCollections" | "listPlatformDocuments" | "getPlatformDocument" | "createImport" | "getImport" | "uploadImportSource" | "updateImport" | "startImport" | "cancelImport" | "resumeImport" | "createBackup" | "listBackups" | "restoreBackup" | "getBackupPolicy" | "setBackupPolicy" | "getRestoreWindow" | "planPointInTime" | "restorePointInTime" | "getBackupDestination" | "setBackupDestination" | "deleteBackupDestination" | "getProjectUsage" | "getProjectAnalytics" | "getProjectReplication" | "getDatabaseUsage" | "getDatabaseAnalytics" | "getDatabaseReplication" | "createIndex" | "listIndexes" | "dropIndex" | "getAutoIndexPolicy" | "setAutoIndexPolicy" | "listIndexRecommendations" | "applyIndexRecommendation" | "getDatabaseSchema" | "inferCollectionSchema" | "declareCollectionSchema" | "listQueryShapes" | "createSavedQuery" | "listSavedQueries" | "getSavedQuery" | "updateSavedQuery" | "deleteSavedQuery"} ManagementOperation */
+const saved = "/v1/projects/{project}/saved-queries";
+/** @type {readonly import("./routes.js").V1Route[]} */
+export const managementV1Routes = Object.freeze([
+  route("getShapeManifest", "GET", "/v1/projects/{project}/databases/{database}/collections/{collection}/shape/manifest"),
+  route("healthz", "GET", "/healthz"),
+  route("readyz", "GET", "/readyz"),
+  route("backupz", "GET", "/backupz"),
+  route("replicationHealth", "GET", "/health/replication"),
+  route("listPlatformDatabases", "GET", "/v1/platform/databases"),
+  route("listPlatformCollections", "GET", "/v1/platform/databases/{database}/collections"),
+  route("listPlatformDocuments", "GET", "/v1/platform/databases/{database}/collections/{collection}/documents"),
+  route("getPlatformDocument", "GET", "/v1/platform/databases/{database}/collections/{collection}/documents/by-key"),
+  route("createImport", "POST", "/v1/projects/{project}/databases/{database}/import", 201),
+  route("getImport", "GET", "/v1/projects/{project}/databases/{database}/import", 200),
+  route("uploadImportSource", "PUT", "/v1/projects/{project}/databases/{database}/import/source", 200),
+  route("updateImport", "PATCH", "/v1/projects/{project}/databases/{database}/import", 202),
+  route("startImport", "POST", "/v1/projects/{project}/databases/{database}/import/start", 202),
+  route("cancelImport", "POST", "/v1/projects/{project}/databases/{database}/import/cancel", 202),
+  route("resumeImport", "POST", "/v1/projects/{project}/databases/{database}/import/resume", 202),
+  route("createBackup", "POST", "/v1/projects/{project}/databases/{database}/backups", 201),
+  route("listBackups", "GET", "/v1/projects/{project}/databases/{database}/backups", 200),
+  route("restoreBackup", "POST", "/v1/projects/{project}/databases/{database}/backups/{backup}/restore", 201),
+  route("getBackupPolicy", "GET", "/v1/projects/{project}/databases/{database}/backup-policy", 200),
+  route("setBackupPolicy", "PUT", "/v1/projects/{project}/databases/{database}/backup-policy", 200),
+  route("getRestoreWindow", "GET", "/v1/projects/{project}/databases/{database}/point-in-time", 200),
+  route("planPointInTime", "POST", "/v1/projects/{project}/databases/{database}/point-in-time/plan", 200),
+  route("restorePointInTime", "POST", "/v1/projects/{project}/databases/{database}/point-in-time/restore", 201),
+  route("getBackupDestination", "GET", "/v1/projects/{project}/backup-destination", 200),
+  route("setBackupDestination", "PUT", "/v1/projects/{project}/backup-destination", 200),
+  route("deleteBackupDestination", "DELETE", "/v1/projects/{project}/backup-destination", 204),
+  route("getProjectUsage", "GET", "/v1/projects/{project}/usage"),
+  route("getProjectAnalytics", "GET", "/v1/projects/{project}/analytics"),
+  route("getProjectReplication", "GET", "/v1/projects/{project}/replication"),
+  route("getDatabaseUsage", "GET", "/v1/projects/{project}/databases/{database}/usage"),
+  route("getDatabaseAnalytics", "GET", "/v1/projects/{project}/databases/{database}/analytics"),
+  route("getDatabaseReplication", "GET", "/v1/projects/{project}/databases/{database}/replication"),
+  route("createIndex", "POST", "/v1/projects/{project}/databases/{database}/indexes", 201),
+  route("listIndexes", "GET", "/v1/projects/{project}/databases/{database}/indexes", 200),
+  route("dropIndex", "DELETE", "/v1/projects/{project}/databases/{database}/indexes/{index}", 204),
+  route("getAutoIndexPolicy", "GET", "/v1/projects/{project}/databases/{database}/auto-index/{collection}", 200),
+  route("setAutoIndexPolicy", "PUT", "/v1/projects/{project}/databases/{database}/auto-index/{collection}", 200),
+  route("listIndexRecommendations", "GET", "/v1/projects/{project}/databases/{database}/index-recommendations", 200),
+  route("applyIndexRecommendation", "POST", "/v1/projects/{project}/databases/{database}/index-recommendations/{recommendation}/apply", 201),
+  route("getDatabaseSchema", "GET", "/v1/projects/{project}/databases/{database}/schema"),
+  route("inferCollectionSchema", "GET", "/v1/projects/{project}/databases/{database}/schema/{collection}"),
+  route("declareCollectionSchema", "PUT", "/v1/projects/{project}/databases/{database}/schema/{collection}"),
+  route("listQueryShapes", "GET", "/v1/projects/{project}/databases/{database}/query-shapes"),
+  route("createSavedQuery", "POST", saved, 201),
+  route("listSavedQueries", "GET", saved),
+  route("getSavedQuery", "GET", `${saved}/{query}`),
+  route("updateSavedQuery", "PUT", `${saved}/{query}`),
+  route("deleteSavedQuery", "DELETE", `${saved}/{query}`, 204),
+]);
+
+/** @param {ManagementOperation} operation @param {import("./routes.js").V1Route["method"]} method @param {string} pathTemplate @param {number} [status] @returns {import("./routes.js").V1Route} */
+function route(operation, method, pathTemplate, status = 200) {
+  const write = method !== "GET" && operation !== "planPointInTime";
+  const noBody = ["createBackup", "applyIndexRecommendation", "cancelImport", "resumeImport"].includes(operation);
+  return Object.freeze({ operation, method, pathTemplate,
+    permission: operation === "getShapeManifest" ? "documents:read" : pathTemplate.startsWith("/v1/platform/") ? "platform-admin" : !pathTemplate.startsWith("/v1/") ? "anonymous" : write ? "databases:write" : "databases:read",
+    additionalPermissions: Object.freeze(["createImport", "uploadImportSource", "updateImport", "startImport", "resumeImport"].includes(operation) ? ["documents:write"] : []),
+    requestMediaTypes: Object.freeze(noBody ? [] : operation === "uploadImportSource" ? ["application/octet-stream"] : method === "POST" || method === "PUT" || method === "PATCH" ? ["application/json"] : []),
+    responseMediaType: status === 204 ? "" : "application/json", successStatuses: Object.freeze(operation === "readyz" || operation === "backupz" ? [200, 503] : operation === "applyIndexRecommendation" || operation === "createImport" ? [200, 201] : [status]),
+    idempotencyKey: "none", replaySafe: !write, contract: "docs/terrabase/api.md", contractText: Object.freeze([]),
+  });
+}

package/src/v1/management-validation.js

@@ -0,0 +1,25 @@
+/** @import { V1DatabaseListRequest } from "./catalog.js" */
+/** @param {unknown} request @param {readonly string[]} allowed */
+export function members(request, allowed) {
+  if (request === null || typeof request !== "object" || Array.isArray(request) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(request))) throw new TypeError("Expected a plain request object.");
+  for (const key of Object.keys(request)) if (!allowed.includes(key)) throw new TypeError(`Unknown request member ${key}.`);
+}
+/** @param {object} options */
+export function mutationOptions(options) {
+  if ("idempotencyKey" in options) throw new TypeError("The producer does not support Idempotency-Key; mutations are never replayed.");
+}
+/** @param {V1DatabaseListRequest} request */
+export function pageQuery(request) {
+  members(request, ["after", "limit"]);
+  const query = new URLSearchParams();
+  if (request.after !== undefined) {
+    if (typeof request.after !== "string") throw new TypeError("after must be an opaque string.");
+    query.set("after", request.after);
+  }
+  if (request.limit !== undefined) {
+    if (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > 100) throw new TypeError("limit must be 1-100.");
+    query.set("limit", String(request.limit));
+  }
+  return query;
+}

package/src/v1/routes.js

@@ -1,11 +1,13 @@
-// 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 */
+import { managementV1Routes } from "./management-routes.js";
+// Current TerraBase routes at e30ffdc; readShape is retained from release 6cb9745 only.
+/** @typedef {import("./management-routes.js").ManagementOperation | "readFreeShape" | "getShapeKey" | "getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape" | "runSql" | "checkSql" | "explainSql" | "streamDatabaseChanges" | "listDocuments" | "getCollectionSchema" | "putCollectionSchema" | "deleteCollectionSchema" | "createDatabase" | "listDatabases" | "getDatabase" | "updateDatabase" | "deleteDatabase" | "branchDatabase"} V1Operation */
 /**
  * @typedef {object} V1Route
  * @property {V1Operation} operation
  * @property {"GET" | "PUT" | "POST" | "PATCH" | "DELETE"} method
  * @property {string} pathTemplate
- * @property {"documents:read" | "documents:write" | "shapes:read"} permission
+ * @property {"documents:read" | "documents:write" | "shapes:read" | "databases:read" | "databases:write" | "anonymous" | "platform-admin"} permission
+ * @property {readonly string[]} [additionalPermissions]
  * @property {readonly string[]} requestMediaTypes
  * @property {string} responseMediaType
  * @property {readonly number[]} successStatuses
@@ -18,6 +20,7 @@ const database = "/v1/projects/{project}/databases/{database}";
 const collections = `${database}/collections`;
 const collection = `${collections}/{collection}`;
 const documents = `${collection}/documents`;
+const databases = "/v1/projects/{project}/databases";
 /** @type {readonly V1Route[]} */
 export const v1Routes = Object.freeze(/** @type {V1Route[]} */ ([
   { operation: "getDocument", method: "GET", pathTemplate: `${documents}/by-key`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
@@ -32,10 +35,25 @@ export const v1Routes = Object.freeze(/** @type {V1Route[]} */ ([
   { operation: "listCollections", method: "GET", pathTemplate: collections, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
   { operation: "dropCollection", method: "DELETE", pathTemplate: collection, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
   { operation: "readShape", method: "GET", pathTemplate: `${collection}/shape`, permission: "shapes:read", requestMediaTypes: [], successStatuses: [200, 307] },
+  { operation: "runSql", method: "POST", pathTemplate: `${database}/sql`, permission: "databases:read", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "checkSql", method: "POST", pathTemplate: `${database}/sql/check`, permission: "databases:read", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "explainSql", method: "POST", pathTemplate: `${database}/sql/explain`, permission: "databases:read", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "streamDatabaseChanges", method: "GET", pathTemplate: `${database}/changes`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "listDocuments", method: "GET", pathTemplate: documents, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "getCollectionSchema", method: "GET", pathTemplate: `${collection}/schema`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "putCollectionSchema", method: "PUT", pathTemplate: `${collection}/schema`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "deleteCollectionSchema", method: "DELETE", pathTemplate: `${collection}/schema`, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "createDatabase", method: "POST", pathTemplate: databases, permission: "databases:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
+  { operation: "listDatabases", method: "GET", pathTemplate: databases, permission: "databases:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "getDatabase", method: "GET", pathTemplate: database, permission: "databases:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "updateDatabase", method: "PATCH", pathTemplate: database, permission: "databases:write", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "deleteDatabase", method: "DELETE", pathTemplate: database, permission: "databases:write", requestMediaTypes: [], successStatuses: [204] },
+  { operation: "branchDatabase", method: "POST", pathTemplate: `${database}/branches`, permission: "databases:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
 ].map(route => ({
-  ...route, responseMediaType: "application/json", idempotencyKey: "none",
-  replaySafe: route.permission !== "documents:write",
-  contract: route.operation === "readShape" ? "docs/shape-reads.md" : "docs/decisions/0004-document-api-v1.md",
+  ...route, responseMediaType: route.operation === "deleteDatabase" ? "" : route.operation === "streamDatabaseChanges" ? "text/event-stream" : "application/json", idempotencyKey: "none",
+  replaySafe: !route.permission.endsWith(":write"),
+  contract: route.operation === "readShape" ? "docs/shape-reads.md" :
+    ["runSql", "checkSql", "explainSql", "streamDatabaseChanges"].includes(route.operation) ? "docs/terrabase/api.md" : "docs/decisions/0004-document-api-v1.md",
   contractText: [],
 }))).map(route => Object.freeze({
   ...route, requestMediaTypes: Object.freeze(route.requestMediaTypes),
@@ -43,7 +61,7 @@ export const v1Routes = Object.freeze(/** @type {V1Route[]} */ ([
 })));
 /** @param {V1Operation} operation @returns {V1Route} */
 export function v1Route(operation) {
-  const route = v1Routes.find(candidate => candidate.operation === operation);
+  const route = [...v1Routes, ...shapeV1Routes, ...managementV1Routes].find(candidate => candidate.operation === operation);
   if (route === undefined) throw new TypeError(`Unknown v1 operation ${operation}.`);
   return route;
 }
@@ -55,3 +73,10 @@ export function v1RoutePath(route, params) {
     return encodeURIComponent(value);
   });
 }
+
+// Proposed free-read protocol, separately inventoried from historical/runtime route evidence.
+/** @type {readonly V1Route[]} */
+export const shapeV1Routes = Object.freeze([
+  Object.freeze({ operation: /** @type {const} */ ("readFreeShape"), method: /** @type {const} */ ("GET"), pathTemplate: `${collection}/shape`, permission: /** @type {const} */ ("documents:read"), requestMediaTypes: Object.freeze([]), responseMediaType: "application/json", successStatuses: Object.freeze([200, 307]), idempotencyKey: /** @type {const} */ ("none"), replaySafe: true, contract: "docs/terrabase/shape-reads.md", contractText: Object.freeze([]) }),
+  Object.freeze({ operation: /** @type {const} */ ("getShapeKey"), method: /** @type {const} */ ("GET"), pathTemplate: `${collection}/shape/keys`, permission: /** @type {const} */ ("documents:read"), requestMediaTypes: Object.freeze([]), responseMediaType: "application/json", successStatuses: Object.freeze([200]), idempotencyKey: /** @type {const} */ ("none"), replaySafe: true, contract: "docs/terrabase/shape-reads.md", contractText: Object.freeze([]) }),
+]);

package/src/v1/saved-queries.js

@@ -0,0 +1,58 @@
+import { requireId } from "../ids.js";
+import { array, malformed, object, string } from "./decode.js";
+import { stringifyExactJson } from "./json.js";
+import { members, mutationOptions, pageQuery } from "./management-validation.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+/** @typedef {{ readonly id: string; readonly name: string; readonly sql: string; readonly createdAt: string; readonly updatedAt: string | null }} V1SavedQuery */
+/** @typedef {{ readonly name: string; readonly sql: string }} V1SavedQueryRequest */
+/** @typedef {{ readonly items: readonly V1SavedQuery[]; readonly next: string | null }} V1SavedQueryPage */
+
+/** @param {import("./json.js").JsonValue | undefined} value @returns {V1SavedQuery} */
+function savedQuery(value) {
+  const raw = object(value, "saved query");
+  return Object.freeze({ id: requireId(raw.id), name: string(raw.name, "saved query name"), sql: string(raw.sql, "saved SQL"),
+    createdAt: string(raw.createdAt, "saved query createdAt"), updatedAt: raw.updatedAt === null ? null : string(raw.updatedAt, "saved query updatedAt") });
+}
+/** @param {V1SavedQueryRequest} request */
+function body(request) {
+  members(request, ["name", "sql"]);
+  if (typeof request.name !== "string" || request.name.trim().length < 1 || request.name.trim().length > 128 ||
+      /[\p{Cc}]/u.test(request.name) || !/[\p{L}\p{N}]/u.test(request.name)) throw new TypeError("name must contain a letter or digit and be 1-128 characters without controls.");
+  if (typeof request.sql !== "string" || request.sql.trim() === "" || request.sql.length > 16_384)
+    throw new TypeError("sql must be a non-empty statement of at most 16384 UTF-16 code units.");
+  return stringifyExactJson({ name: request.name, sql: request.sql }, "saved query");
+}
+
+/** Saved queries belong to the authorized project, independently of database handles. */
+export class V1SavedQueries {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+  /** @param {V1SavedQueryRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1SavedQuery>} */
+  async create(request, options = {}) {
+    mutationOptions(options);
+    return savedQuery((await this.#transport.call("createSavedQuery", {}, { body: body(request), signal: options.signal })).value);
+  }
+  /** @param {import("./catalog.js").V1DatabaseListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1SavedQueryPage>} */
+  async list(request = {}, options = {}) {
+    const raw = object((await this.#transport.call("listSavedQueries", {}, { query: pageQuery(request), signal: options.signal })).value, "saved query page");
+    if (raw.next !== null && (typeof raw.next !== "string" || raw.next === "")) malformed("saved query next");
+    return Object.freeze({ items: Object.freeze(array(raw.items, "saved queries").map(savedQuery)), next: raw.next });
+  }
+  /** @param {string} id @param {V1RequestOptions} [options] @returns {Promise<V1SavedQuery>} */
+  async get(id, options = {}) {
+    return savedQuery((await this.#transport.call("getSavedQuery", { query: requireId(id) }, { signal: options.signal })).value);
+  }
+  /** @param {string} id @param {V1SavedQueryRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1SavedQuery>} */
+  async update(id, request, options = {}) {
+    mutationOptions(options);
+    return savedQuery((await this.#transport.call("updateSavedQuery", { query: requireId(id) }, { body: body(request), signal: options.signal })).value);
+  }
+  /** @param {string} id @param {V1RequestOptions} [options] @returns {Promise<void>} */
+  async delete(id, options = {}) {
+    mutationOptions(options);
+    await this.#transport.call("deleteSavedQuery", { query: requireId(id) }, { signal: options.signal });
+  }
+}

package/src/v1/shape-crypto.js

@@ -0,0 +1,125 @@
+const MAGIC = "TBS1";
+const HEADER_BYTES = 70;
+const KEY_ID_BYTES = 26;
+const FRAME_BYTES = 1048576;
+const MAX_PLAINTEXT_BYTES = 8388608;
+const TAG_BYTES = 16;
+const LAST_FRAME_FLAG = 0x80000000;
+const LENGTH_MASK = 0x7fffffff;
+const MAX_UINT64 = 2n ** 64n - 1n;
+
+/**
+ * @typedef {object} ShapeObjectRequest
+ * @property {string} handle The shape handle this client requested, e.g. `h1-…`.
+ * @property {string} offset Canonical offset of the object's URL, e.g. `2` or `snap.0.0`.
+ * @property {string} epoch Decimal epoch the client expects in the header.
+ * @property {string} keyId The 26-character project data key id the client expects in the header.
+ * @property {Uint8Array} key Raw 32-byte epoch key `K_e`.
+ */
+
+/**
+ * Verifies and decrypts one TBS1 sealed shape object. The plaintext is returned only when the
+ * header, every frame tag and the framing rules pass. Any failure throws and yields no bytes.
+ *
+ * @param {Uint8Array} input Exact TBS1 object bytes.
+ * @param {ShapeObjectRequest} request
+ * @returns {Promise<Uint8Array>}
+ */
+export async function decryptShapeObject(input, { handle, offset, epoch, keyId, key: keyInput }) {
+  if (input.byteLength > HEADER_BYTES + 9 * (4 + TAG_BYTES) + MAX_PLAINTEXT_BYTES)
+    throw new TypeError("TBS1 object exceeds the maximum sealed size");
+  // WebCrypto needs ArrayBuffer-backed views; copying keeps the caller's (possibly shared) buffer out of it.
+  const bytes = Uint8Array.from(input);
+  const key = Uint8Array.from(keyInput);
+  if (key.byteLength !== 32) throw new TypeError("TBS1 epoch key must be 32 bytes");
+  if (typeof keyId !== "string" || !/^[\x00-\x7f]{26}$/u.test(keyId))
+    throw new TypeError("TBS1 key id must be 26 ASCII characters");
+  if (bytes.byteLength < HEADER_BYTES) throw new TypeError("TBS1 header is short");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (new TextDecoder().decode(bytes.subarray(0, 4)) !== MAGIC) throw new TypeError("TBS1 magic mismatch");
+  if (view.getBigUint64(4) !== parseEpoch(epoch)) throw new TypeError("TBS1 epoch mismatch");
+  if (new TextDecoder().decode(bytes.subarray(12, 12 + KEY_ID_BYTES)) !== keyId) throw new TypeError("TBS1 key id mismatch");
+
+  const header = bytes.subarray(0, HEADER_BYTES);
+  const { subtle } = globalThis.crypto;
+  const epochKey = await subtle.importKey("raw", key, "HKDF", false, ["deriveKey"]);
+  const objectKey = await subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: bytes.slice(38, HEADER_BYTES),
+      info: new TextEncoder().encode(`TBS1 object\u0000${handle}\u0000${offset}`),
+    },
+    epochKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["decrypt"],
+  );
+
+  const plaintextParts = [];
+  let plaintextTotal = 0;
+  let position = HEADER_BYTES;
+  for (let index = 0; ; index += 1) {
+    if (position + 4 > bytes.byteLength) throw new TypeError("TBS1 object ends before its last frame");
+    const lengthWord = view.getUint32(position);
+    const last = (lengthWord & LAST_FRAME_FLAG) !== 0;
+    const length = lengthWord & LENGTH_MASK;
+    if (last ? length >= FRAME_BYTES : length !== FRAME_BYTES) throw new TypeError("TBS1 frame length is invalid");
+    plaintextTotal += length;
+    if (plaintextTotal > MAX_PLAINTEXT_BYTES) throw new TypeError("TBS1 plaintext exceeds 8 MiB");
+    const bodyStart = position + 4;
+    const frameEnd = bodyStart + length + TAG_BYTES;
+    if (frameEnd > bytes.byteLength) throw new TypeError("TBS1 object is truncated");
+    const nonce = concat(new Uint8Array(4), uint64(index));
+    const additionalData = concat(header, uint64(index), bytes.subarray(position, bodyStart));
+    try {
+      const plaintext = await subtle.decrypt(
+        { name: "AES-GCM", iv: nonce, additionalData, tagLength: 128 },
+        objectKey,
+        bytes.subarray(bodyStart, frameEnd),
+      );
+      plaintextParts.push(new Uint8Array(plaintext));
+    } catch {
+      throw new TypeError("TBS1 frame failed authentication");
+    }
+    position = frameEnd;
+    if (last) break;
+  }
+  if (position !== bytes.byteLength) throw new TypeError("TBS1 object has bytes after its last frame");
+  return concat(...plaintextParts);
+}
+
+/**
+ * @param {string} value
+ * @returns {bigint}
+ */
+function parseEpoch(value) {
+  if (!/^(0|[1-9][0-9]*)$/u.test(value)) throw new TypeError("TBS1 epoch must be a canonical decimal");
+  const epoch = BigInt(value);
+  if (epoch > MAX_UINT64) throw new TypeError("TBS1 epoch exceeds uint64");
+  return epoch;
+}
+
+/**
+ * @param {number} value
+ * @returns {Uint8Array}
+ */
+function uint64(value) {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigUint64(0, BigInt(value));
+  return out;
+}
+
+/**
+ * @param {...Uint8Array} parts
+ * @returns {Uint8Array<ArrayBuffer>}
+ */
+function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((total, part) => total + part.byteLength, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.byteLength;
+  }
+  return out;
+}

package/src/v1/shape-manifest.js

@@ -0,0 +1,31 @@
+import { requireId } from "../ids.js";
+import { malformed } from "./decode.js";
+import { list, numeric, record, text } from "./management-decode.js";
+import { requireFilter } from "./filter.js";
+import { stringifyExactJson } from "./json.js";
+import { requireShapeHandle, requireShapeOffset } from "./shapes.js";
+/** @import { V1Transport } from "./transport.js" */
+const manifest = record({ handle: requireShapeHandle, objects: list(record({ offset: requireShapeOffset, next_offset: requireShapeOffset,
+  binding: text, object: text, url: text, expires_at: text, epoch: text, key_id: requireId, sha256: text, size: numeric })) });
+/** @typedef {ReturnType<typeof manifest>} V1ShapeManifest */
+/** @typedef {{readonly handle: string; readonly offset: string; readonly where?: import("./filter.js").V1Filter}} V1ShapeManifestRequest */
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1ShapeManifestRequest} request @param {AbortSignal | undefined} signal @returns {Promise<V1ShapeManifest>} */
+export async function readShapeManifest(transport, params, request, signal) {
+  const handle = requireShapeHandle(request.handle);
+  const offset = requireShapeOffset(request.offset);
+  if (offset === "-1") throw new TypeError("A manifest requires a snapshot or log offset.");
+  const query = new URLSearchParams({ handle, offset });
+  if (request.where !== undefined) query.set("where", stringifyExactJson(requireFilter(request.where), "shape filter"));
+  const response = await transport.call("getShapeManifest", params, { query, cache: "no-store", signal });
+  const result = manifest(response.value);
+  if (result.handle !== handle || result.objects.length > 8) malformed("shape manifest binding");
+  let next = offset;
+  for (const item of result.objects) {
+    if (item.offset !== next || item.next_offset === item.offset || item.offset === "-1" || item.next_offset === "-1" ||
+        !/^[a-f0-9]{64}$/u.test(item.sha256) || !/^(?:0|[1-9][0-9]*)$/u.test(item.epoch)) malformed("shape manifest object");
+    const url = new URL(item.url);
+    if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.hash !== "") malformed("shape object URL");
+    next = item.next_offset;
+  }
+  return result;
+}

package/src/v1/shape-reader.js

@@ -0,0 +1,212 @@
+// The proposed free-read v1 protocol is separate from the historical shape() contract.
+import { requireId } from "../ids.js";
+import { malformed, object, string } from "./decode.js";
+import { decodeShapePage, encodeShapeRequest, requireShapeHandle, requireShapeOffset } from "./shapes.js";
+import { decryptShapeObject } from "./shape-crypto.js";
+import { parseExactJson } from "./json.js";
+import { TerraBaseV1Error } from "./errors.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1ShapeRequest, V1ShapePage } from "./shapes.js" */
+/** @typedef {{handle: string; offset: string; epoch: string; keyId: string}} V1SealedShapePosition */
+/** @typedef {{ latestEpoch: bigint; keys: Map<string, { epoch: bigint; key: Uint8Array }> }} ShapeKeys */
+/** @type {WeakMap<V1Transport, Map<string, ShapeKeys>>} Keys stay scoped to a credential, database and collection. */
+const shapeKeys = new WeakMap();
+/** @param {Readonly<Record<string, string>>} params */
+const keyScope = params => JSON.stringify([params.database, params.collection]);
+/**
+ * A refetch invalidates both the materialized state and any epoch keys for that collection.
+ * @param {V1Transport} transport @param {Readonly<Record<string, string>>} params
+ * @param {"readFreeShape" | "getShapeKey"} operation @param {import("./transport.js").V1CallOptions} options
+ */
+async function shapeCall(transport, params, operation, options) {
+  try { return await transport.call(operation, params, options); }
+  catch (error) {
+    if (error instanceof TerraBaseV1Error && error.status === 409 && error.code === "must_refetch")
+      shapeKeys.get(transport)?.delete(keyScope(params));
+    throw error;
+  }
+}
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @returns {ShapeKeys} */
+function currentKeys(transport, params) {
+  let scopes = shapeKeys.get(transport);
+  if (scopes === undefined) { scopes = new Map(); shapeKeys.set(transport, scopes); }
+  const scope = keyScope(params);
+  let cache = scopes.get(scope);
+  if (cache === undefined) { cache = { latestEpoch: 0n, keys: new Map() }; scopes.set(scope, cache); }
+  // Expiry is lazy; a higher served epoch also protects against a regressed client clock.
+  const epoch = BigInt(Math.floor(Date.now() / 600_000));
+  if (epoch > cache.latestEpoch) cache.latestEpoch = epoch;
+  for (const [id, entry] of cache.keys) if (entry.epoch < cache.latestEpoch) cache.keys.delete(id);
+  return cache;
+}
+/** @param {unknown} value @returns {string} */
+function decimal(value) {
+  const text = requireShapeOffset(value);
+  if (text === "-1" || text.startsWith("snap.")) malformed("shape decimal");
+  return text;
+}
+/** @param {unknown} value @returns {string} */
+function resumeToken(value) {
+  // Resume envelopes are opaque: validate header safety, never decode or normalize them.
+  if (typeof value !== "string" || !/^[A-Za-z0-9_-]+$/u.test(value)) malformed("shape resume cursor");
+  return value;
+}
+/** @param {string} offset @returns {string} */
+function snapshotKey(offset) {
+  const encoded = offset.split(".")[2] ?? "";
+  return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+    Uint8Array.from(atob(encoded.replace(/-/gu, "+").replace(/_/gu, "/")), c => c.charCodeAt(0)),
+  );
+}
+/** @param {import("./json.js").JsonValue | undefined} value @param {Headers} headers @returns {V1ShapePage} */
+export function decodeFreeShapePage(value, headers) {
+  const page = decodeShapePage(value, headers);
+  const raw = object(value, "free shape page");
+  const covered = decimal(raw.covered_offset);
+  const values = decimal(raw.values_at);
+  resumeToken(raw.cursor_resume);
+  if (page.offset === "-1" || page.nextOffset === "-1" || BigInt(values) < BigInt(covered)) malformed("shape coverage");
+  if (page.offset.startsWith("snap.")) {
+    const head = page.offset.split(".")[1];
+    if (covered !== head || values !== head || page.upToDate || page.changes.length !== 1 || page.changes[0]?.offset !== head ||
+        page.changes[0]?.ops.some(op => op.op !== "upsert") ||
+        (page.nextOffset.startsWith("snap.") ? page.nextOffset.split(".")[1] !== head || page.nextOffset === page.offset : page.nextOffset !== head))
+      malformed("shape snapshot coverage");
+    if (page.nextOffset.startsWith("snap.") && (page.nextOffset.endsWith(".0") ||
+        (!page.offset.endsWith(".0") && snapshotKey(page.nextOffset) <= snapshotKey(page.offset)))) malformed("shape snapshot progression");
+  } else {
+    if (page.nextOffset.startsWith("snap.") || page.nextOffset !== covered || BigInt(covered) < BigInt(page.offset) ||
+        (!page.upToDate && covered === page.offset)) malformed("shape log coverage");
+    let previous = BigInt(page.offset);
+    for (const change of page.changes) {
+      const offset = BigInt(decimal(change.offset));
+      if (offset <= previous || offset > BigInt(covered)) malformed("shape commit order");
+      previous = offset;
+    }
+  }
+  for (const change of page.changes) {
+    let previousId;
+    for (const op of change.ops) {
+      if (previousId !== undefined && op.id <= previousId) malformed("shape document order");
+      previousId = op.id;
+    }
+  }
+  return page;
+}
+/**
+ * Follows exactly one authorized same-route 307; credentials never follow an arbitrary Location.
+ * @param {V1Transport} transport @param {Readonly<Record<string,string>>} params
+ * @param {V1ShapeRequest} request @param {AbortSignal | undefined} signal
+ * @param {string | undefined} [ifNoneMatch] A complete entity-tag list or *; 304 throws not_modified with response headers.
+ * @returns {Promise<V1ShapePage>}
+ */
+export async function readShapePage(transport, params, request, signal, ifNoneMatch) {
+  const isResume = (request.offset ?? "-1") === "-1" && request.cursor !== undefined;
+  if (isResume && (request.handle !== undefined || request.live !== undefined)) throw new TypeError("Shape resume requires offset=-1 without handle or live.");
+  const query = encodeShapeRequest(isResume ? { ...request, cursor: undefined } : request);
+  // Canonical filter size is checked by the producer; check our exact wire spelling here.
+  if (new TextEncoder().encode(query.get("where") ?? "").byteLength > 8192) throw new TypeError("Shape filters are limited to 8 KiB of UTF-8.");
+  if (query.get("offset") === "-1" && query.has("handle")) throw new TypeError("Shape bootstrap must omit handle.");
+  /** @type {Record<string,string>} */
+  const headers = {};
+  if (ifNoneMatch !== undefined) {
+    if (typeof ifNoneMatch !== "string" || !/^[ \t]*(?:\*|(?:W\/)?"[\x21\x23-\x7e\x80-\xff]*"(?:[ \t]*,[ \t]*(?:W\/)?"[\x21\x23-\x7e\x80-\xff]*")*)[ \t]*$/u.test(ifNoneMatch))
+      throw new TypeError("ifNoneMatch must be * or a list of quoted entity tags.");
+    headers["If-None-Match"] = ifNoneMatch;
+  }
+  const source = new URL(await transport.url("readFreeShape", params, signal));
+  if (isResume) {
+    query.set("cursor", resumeToken(request.cursor));
+    // The producer reserves 64 bytes for request-line framing in its 8 KiB ceiling.
+    if (new TextEncoder().encode(`${source.pathname}?${query}`).length > 8192 - 64) {
+      headers["TB-Shape-Resume"] = resumeToken(request.cursor);
+      query.delete("cursor");
+    }
+  }
+  let response = await shapeCall(transport, params, "readFreeShape", { query, headers, signal });
+  if (response.status === 307) {
+    if (query.get("offset") !== "-1") malformed("unexpected shape redirect");
+    const location = response.headers.get("location");
+    if (location === null) malformed("shape redirect Location");
+    const target = new URL(location, source);
+    if (target.origin !== source.origin || target.pathname !== source.pathname || target.username !== "" || target.password !== "" || target.hash !== "") malformed("shape redirect target");
+    for (const key of target.searchParams.keys()) {
+      if (!["where", "handle", "offset"].includes(key) || target.searchParams.getAll(key).length !== 1) malformed("shape redirect query");
+    }
+    const handle = requireShapeHandle(target.searchParams.get("handle"));
+    const offset = requireShapeOffset(target.searchParams.get("offset"));
+    if (offset === "-1" || (!isResume && !/^snap\.[0-9]+\.0$/u.test(offset)) || (isResume && offset.startsWith("snap."))) malformed("shape redirect offset");
+    if (target.searchParams.has("where") !== query.has("where")) malformed("shape redirect filter");
+    // Keep the caller's validated filter: the server's canonical spelling must not broaden it.
+    query.delete("cursor");
+    delete headers["TB-Shape-Resume"];
+    query.set("handle", handle);
+    query.set("offset", offset);
+    response = await shapeCall(transport, params, "readFreeShape", { query, headers, signal });
+    if (response.status !== 200) malformed("repeated shape redirect");
+  } else if (query.get("offset") === "-1") malformed("shape bootstrap requires redirect");
+  const page = decodeFreeShapePage(response.value, response.headers);
+  if (page.handle !== query.get("handle") || page.offset !== query.get("offset")) malformed("shape response position");
+  const inputCursor = query.get("cursor");
+  if (request.live === true && (page.cursor === undefined || (inputCursor !== null && BigInt(page.cursor) <= BigInt(inputCursor)))) malformed("shape live cursor advance");
+  return page;
+}
+/**
+ * Reuse process-memory keys for this handle/epoch/KID; fetch misses without HTTP cache reuse.
+ * @param {V1Transport} transport @param {Readonly<Record<string,string>>} params
+ * @param {Uint8Array} bytes @param {V1SealedShapePosition} position @param {AbortSignal | undefined} signal
+ * @returns {Promise<V1ShapePage>}
+ */
+export async function decryptSealedShapePage(transport, params, bytes, position, signal) {
+  const handle = requireShapeHandle(position.handle);
+  const offset = requireShapeOffset(position.offset);
+  if (offset === "-1") throw new TypeError("Sealed shapes require a snapshot or log offset.");
+  if (typeof position.epoch !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(position.epoch) || BigInt(position.epoch) > (1n << 64n) - 1n) throw new TypeError("Shape epoch must be a canonical uint64.");
+  const epoch = position.epoch;
+  const keyId = requireId(position.keyId, "Shape key ID");
+  signal?.throwIfAborted();
+  const cache = currentKeys(transport, params);
+  const cacheId = JSON.stringify([handle, epoch, keyId]);
+  let raw = cache.keys.get(cacheId)?.key;
+  if (raw === undefined) {
+    const query = new URLSearchParams({ handle, epoch, key_id: keyId });
+    const response = await shapeCall(transport, params, "getShapeKey", { query, cache: "no-store", signal });
+    const key = object(response.value, "shape epoch key");
+    if (key.handle !== handle || key.epoch !== epoch || key.key_id !== keyId) malformed("shape epoch key binding");
+    const encoded = string(key.key, "shape epoch key");
+    if (!/^[A-Za-z0-9_-]{43}$/u.test(encoded)) malformed("shape epoch key encoding");
+    raw = Uint8Array.from(atob(encoded.replace(/-/gu, "+").replace(/_/gu, "/")), c => c.charCodeAt(0));
+    if (btoa(String.fromCharCode(...raw)).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "") !== encoded) malformed("shape epoch key encoding");
+    const servedEpoch = BigInt(epoch);
+    const active = currentKeys(transport, params);
+    if (active === cache && servedEpoch >= cache.latestEpoch) {
+      cache.latestEpoch = servedEpoch;
+      for (const [id, entry] of cache.keys) if (entry.epoch < servedEpoch) cache.keys.delete(id);
+      cache.keys.set(cacheId, { epoch: servedEpoch, key: raw });
+    }
+  }
+  const plaintext = await decryptShapeObject(bytes, { handle, offset, epoch, keyId, key: raw });
+  signal?.throwIfAborted();
+  const page = decodeFreeShapePage(parseExactJson(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(plaintext)), new Headers());
+  if (page.handle !== handle || page.offset !== offset || page.upToDate) malformed("sealed shape position");
+  return page;
+}
+
+/** @typedef {{readonly handle: string; readonly epoch: string; readonly keyId: string}} V1ShapeKeyRequest */
+/** @typedef {V1ShapeKeyRequest & {readonly key: Uint8Array}} V1ShapeKey */
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1ShapeKeyRequest} request @param {AbortSignal | undefined} signal @returns {Promise<V1ShapeKey>} */
+export async function readShapeKey(transport, params, request, signal) {
+  const handle = requireShapeHandle(request.handle);
+  const epoch = decimal(request.epoch);
+  const keyId = requireId(request.keyId);
+  const response = await shapeCall(transport, params, "getShapeKey", {
+    query: new URLSearchParams({ handle, epoch, key_id: keyId }), cache: "no-store", signal,
+  });
+  const key = object(response.value, "shape epoch key");
+  if (key.handle !== handle || key.epoch !== epoch || key.key_id !== keyId) malformed("shape epoch key binding");
+  const encoded = string(key.key, "shape key");
+  if (!/^[A-Za-z0-9_-]{43}$/u.test(encoded)) malformed("shape key encoding");
+  const bytes = Uint8Array.from(atob(encoded.replace(/-/gu, "+").replace(/_/gu, "/")), c => c.charCodeAt(0));
+  if (btoa(String.fromCharCode(...bytes)).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "") !== encoded) malformed("shape key encoding");
+  return Object.freeze({ handle, epoch, keyId, key: bytes });
+}