terrascale 0.3.0 → 1.0.0

package/src/v1/json.js

@@ -0,0 +1,335 @@
+// Lossless JSON for the TerraBase v1 Documents API.
+//
+// TerraBase numbers are exact decimals with up to 128 significant digits
+// (api-v1.md). Responses are parsed with JSON.parse source text access, so a
+// number is returned as a JavaScript number only when that number denotes the
+// same decimal value as the wire text; every other number becomes an
+// ExactDecimal holding the original text. Requests are encoded with
+// JSON.rawJSON, so ExactDecimal and bigint values reach the server unchanged.
+
+const decimalGrammar = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/u;
+const maximumIntegerExponent = 4096n;
+
+/**
+ * @typedef {object} CanonicalDecimal
+ * @property {boolean} negative
+ * @property {string} digits Significant digits without leading or trailing zeros; empty for zero.
+ * @property {bigint} exponent The value is digits × 10^exponent.
+ */
+
+/**
+ * @param {string} text
+ * @returns {CanonicalDecimal | undefined}
+ */
+function canonicalDecimal(text) {
+  const match = /^(-)?(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/u.exec(text);
+  if (match === null) return undefined;
+  const fraction = match[3] ?? "";
+  let digits = `${match[2]}${fraction}`.replace(/^0+/u, "");
+  let exponent = BigInt(match[4] ?? "0") - BigInt(fraction.length);
+  if (digits === "") return { negative: false, digits: "", exponent: 0n };
+  const trimmed = digits.replace(/0+$/u, "");
+  exponent += BigInt(digits.length - trimmed.length);
+  digits = trimmed;
+  return { negative: match[1] === "-", digits, exponent };
+}
+
+/**
+ * @param {string} left
+ * @param {string} right
+ * @returns {boolean}
+ */
+function sameDecimal(left, right) {
+  const a = canonicalDecimal(left);
+  const b = canonicalDecimal(right);
+  return (
+    a !== undefined &&
+    b !== undefined &&
+    a.negative === b.negative &&
+    a.digits === b.digits &&
+    a.exponent === b.exponent
+  );
+}
+
+/** @returns {(text: string) => unknown} */
+function rawJsonFactory() {
+  const factory = /** @type {{ rawJSON?: unknown }} */ (
+    /** @type {unknown} */ (JSON)
+  ).rawJSON;
+  if (typeof factory !== "function")
+    throw new TypeError(
+      "TerraBase v1 requires JSON.rawJSON and JSON.parse source text access (Node.js 22+, current browsers) for exact numbers.",
+    );
+  return /** @type {(text: string) => unknown} */ (factory);
+}
+
+/**
+ * An exact decimal number as it travels on the wire. Values that a JavaScript
+ * number cannot represent exactly (large integers, long fractions) are
+ * returned as ExactDecimal; it serializes back to the identical JSON text.
+ */
+export class ExactDecimal {
+  /** @type {string} */
+  #text;
+
+  /** @param {string} text A JSON number literal. */
+  constructor(text) {
+    if (typeof text !== "string" || !decimalGrammar.test(text))
+      throw new TypeError("ExactDecimal requires a JSON number literal.");
+    this.#text = text;
+    Object.freeze(this);
+  }
+
+  /**
+   * @param {ExactDecimal | bigint | number | string} value
+   * @returns {ExactDecimal}
+   */
+  static from(value) {
+    if (value instanceof ExactDecimal) return value;
+    if (typeof value === "bigint") return new ExactDecimal(value.toString());
+    if (typeof value === "number") {
+      if (!Number.isFinite(value))
+        throw new TypeError("TerraBase numbers must be finite.");
+      return new ExactDecimal(String(value));
+    }
+    return new ExactDecimal(value);
+  }
+
+  /** @returns {string} The exact JSON number text. */
+  toString() {
+    return this.#text;
+  }
+
+  /** @returns {unknown} A raw JSON value that serializes as the exact text. */
+  toJSON() {
+    return rawJsonFactory()(this.#text);
+  }
+
+  /** @returns {number} The nearest JavaScript number; may lose precision. */
+  toNumber() {
+    return Number(this.#text);
+  }
+
+  /** @returns {boolean} */
+  isInteger() {
+    return /** @type {CanonicalDecimal} */ (canonicalDecimal(this.#text)).exponent >= 0n;
+  }
+
+  /**
+   * @returns {bigint} The exact integer value.
+   * @throws {RangeError} When the value is not an integer.
+   */
+  toBigInt() {
+    const value = /** @type {CanonicalDecimal} */ (canonicalDecimal(this.#text));
+    if (value.exponent < 0n)
+      throw new RangeError(`${this.#text} is not an integer.`);
+    if (value.exponent > maximumIntegerExponent)
+      throw new RangeError(`${this.#text} is too large to expand.`);
+    if (value.digits === "") return 0n;
+    const magnitude = BigInt(
+      `${value.digits}${"0".repeat(Number(value.exponent))}`,
+    );
+    return value.negative ? -magnitude : magnitude;
+  }
+
+  /**
+   * Exact decimal equality: 1, 1.0 and 1e0 are equal.
+   * @param {ExactDecimal | bigint | number | string} other
+   * @returns {boolean}
+   */
+  equals(other) {
+    return sameDecimal(this.#text, ExactDecimal.from(other).toString());
+  }
+
+  /** @returns {string} */
+  [Symbol.for("nodejs.util.inspect.custom")]() {
+    return `ExactDecimal(${this.#text})`;
+  }
+}
+
+/**
+ * A decoded JSON value. Numbers are `number` when exact, else ExactDecimal.
+ * @typedef {null | boolean | number | string | ExactDecimal | JsonArray | JsonObject} JsonValue
+ */
+/** @typedef {JsonValue[]} JsonArray */
+/** @typedef {{ [key: string]: JsonValue }} JsonObject */
+
+/**
+ * A JSON value accepted in requests: bigint and ExactDecimal encode exactly.
+ * @typedef {null | boolean | number | bigint | string | ExactDecimal | JsonInputArray | JsonInputObject} JsonInput
+ */
+/** @typedef {readonly JsonInput[]} JsonInputArray */
+/** @typedef {{ readonly [key: string]: JsonInput }} JsonInputObject */
+
+/**
+ * A JSON.parse reviver that maps every number through `map(source text)`.
+ * @param {(source: unknown) => unknown} map
+ * @returns {(key: string, value: unknown) => unknown}
+ */
+function sourceReviver(map) {
+  /**
+   * @param {string} _key
+   * @param {unknown} value
+   * @param {{ source?: unknown }} [context]
+   * @returns {unknown}
+   */
+  function revive(_key, value, context) {
+    return typeof value === "number" ? map(context?.source) ?? value : value;
+  }
+  return revive;
+}
+
+let sourceAccess = /** @type {boolean | undefined} */ (undefined);
+
+/** @returns {void} */
+function requireSourceAccess() {
+  if (sourceAccess === undefined) {
+    let seen;
+    JSON.parse("1", sourceReviver((source) => {
+      seen = source;
+    }));
+    sourceAccess = seen === "1" && typeof (/** @type {{ rawJSON?: unknown }} */ (/** @type {unknown} */ (JSON)).rawJSON) === "function";
+  }
+  if (!sourceAccess)
+    throw new TypeError(
+      "TerraBase v1 requires JSON.rawJSON and JSON.parse source text access (Node.js 22+, current browsers) for exact numbers.",
+    );
+}
+
+/**
+ * @param {string} source
+ * @returns {number | ExactDecimal}
+ */
+function exactNumber(source) {
+  const value = Number(source);
+  return Number.isFinite(value) && sameDecimal(source, String(value))
+    ? value
+    : new ExactDecimal(source);
+}
+
+/**
+ * Parses JSON text without losing number precision.
+ * @param {string} text
+ * @returns {JsonValue}
+ */
+export function parseExactJson(text) {
+  requireSourceAccess();
+  return JSON.parse(text, sourceReviver((source) => {
+    if (typeof source !== "string")
+      throw new TypeError("JSON number source text is unavailable.");
+    return exactNumber(source);
+  }));
+}
+
+/**
+ * C# ExactNumber bounds: leading zeros do not count, trailing zeros do.
+ * @param {string} text
+ * @param {string} where
+ * @returns {void}
+ */
+function requireProducerNumber(text, where) {
+  if (!decimalGrammar.test(text)) throw new TypeError(`${where} contains a non-finite number.`);
+  const [mantissa = "", rawExponent = "0"] = text.split(/[eE]/u);
+  const exponent = BigInt(rawExponent);
+  const fraction = mantissa.split(".")[1] ?? "";
+  const digits = mantissa.replace(/[-.]/gu, "").replace(/^0+/u, "");
+  const magnitude = exponent - BigInt(fraction.length) + BigInt(digits.length) - 1n;
+  if (exponent < -1_000_000n || exponent > 1_000_000n || digits.length > 128 ||
+    (digits !== "" && (magnitude < -307n || magnitude > 307n)))
+    throw new TypeError(`${where} numbers have at most 128 significant digits and a magnitude of zero or 1e-307 to below 1e308.`);
+}
+
+/**
+ * Validates a document, merge patch or patch operand against C# RequestJson limits.
+ * @param {unknown} value
+ * @param {string} where
+ * @returns {void}
+ */
+export function assertJsonValue(value, where) {
+  assertJsonInput(value, 0, where, { nodes: 0 });
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} depth
+ * @param {string} where
+ * @param {{ nodes: number }} [budget] Document limits; request envelopes are validated separately.
+ * @returns {void}
+ */
+function assertJsonInput(value, depth, where, budget) {
+  if (budget !== undefined && ++budget.nodes > 4096)
+    throw new TypeError(`${where} holds at most 4096 values.`);
+  if (depth > 64) throw new TypeError(`${where} is nested too deeply.`);
+  if (value === null || typeof value === "boolean") return;
+  if (typeof value === "string") {
+    if (/[\uD800-\uDFFF]/u.test(value)) throw new TypeError(`${where} contains a lone surrogate.`);
+    return;
+  }
+  if (typeof value === "bigint" || typeof value === "number" || value instanceof ExactDecimal) {
+    requireProducerNumber(String(value), where);
+    return;
+  }
+  if (budget !== undefined && typeof value === "object" && depth >= 16)
+    throw new TypeError(`${where} nests at most 16 levels.`);
+  if (Array.isArray(value)) {
+    for (const item of value) assertJsonInput(item, depth + 1, where, budget);
+    return;
+  }
+  if (typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+      throw new TypeError(`${where} contains a non-plain object.`);
+    for (const [key, item] of Object.entries(value)) {
+      if (/[\uD800-\uDFFF]/u.test(key)) throw new TypeError(`${where} contains a lone surrogate member name.`);
+      if (item === undefined)
+        throw new TypeError(`${where} contains an undefined member.`);
+      assertJsonInput(item, depth + 1, where, budget);
+    }
+    return;
+  }
+  throw new TypeError(`${where} contains a value that is not JSON.`);
+}
+
+/**
+ * Encodes a request value exactly. bigint and ExactDecimal keep every digit.
+ * @param {unknown} value
+ * @param {string} where
+ * @returns {string}
+ */
+export function stringifyExactJson(value, where) {
+  requireSourceAccess();
+  assertJsonInput(value, 0, where);
+  const raw = rawJsonFactory();
+  return JSON.stringify(value, (_key, item) =>
+    typeof item === "bigint" ? raw(item.toString()) : item,
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} where
+ * @returns {void}
+ */
+export function assertJsonObject(value, where) {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    value instanceof ExactDecimal
+  )
+    throw new TypeError(`${where} must be a JSON object.`);
+  assertJsonValue(value, where);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is JsonObject}
+ */
+export function isJsonObject(value) {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !(value instanceof ExactDecimal)
+  );
+}

package/src/v1/routes.js

@@ -0,0 +1,57 @@
+// Routes owned by the C# Documents API at 0248ad3 (decision 0004 and shape-reads.md).
+/** @typedef {"getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape"} 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 {readonly string[]} requestMediaTypes
+ * @property {string} responseMediaType
+ * @property {readonly number[]} successStatuses
+ * @property {"none"} idempotencyKey The producer rejects Idempotency-Key.
+ * @property {boolean} replaySafe Informational only; requests are never automatically replayed.
+ * @property {string} contract
+ * @property {readonly string[]} contractText
+ */
+const database = "/v1/projects/{project}/databases/{database}";
+const collections = `${database}/collections`;
+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: "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: "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] },
+  { operation: "getCollection", method: "GET", pathTemplate: collection, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { 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] },
+].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",
+  contractText: [],
+}))).map(route => Object.freeze({
+  ...route, requestMediaTypes: Object.freeze(route.requestMediaTypes),
+  successStatuses: Object.freeze(route.successStatuses), contractText: Object.freeze(route.contractText),
+})));
+/** @param {V1Operation} operation @returns {V1Route} */
+export function v1Route(operation) {
+  const route = v1Routes.find(candidate => candidate.operation === operation);
+  if (route === undefined) throw new TypeError(`Unknown v1 operation ${operation}.`);
+  return route;
+}
+/** @param {V1Route} route @param {Readonly<Record<string, string>>} params @returns {string} */
+export function v1RoutePath(route, params) {
+  return route.pathTemplate.replace(/\{([a-z_]+)\}/gu, (_match, name) => {
+    const value = params[name];
+    if (value === undefined) throw new TypeError(`Missing path parameter ${name}.`);
+    return encodeURIComponent(value);
+  });
+}

package/src/v1/shapes.js

@@ -0,0 +1,145 @@
+// Current C# GET collection/shape contract (docs/shape-reads.md).
+import { array, boolean, malformed, object, string, u64 } from "./decode.js";
+import { requireFilter } from "./filter.js";
+import { parseU64, requireVersion } from "./ids.js";
+import { stringifyExactJson } from "./json.js";
+/**
+ * @import { JsonObject, JsonValue } from "./json.js"
+ * @import { V1Filter } from "./filter.js"
+ * @import { V1Transport } from "./transport.js"
+ */
+/**
+ * @typedef {object} V1ShapeRequest
+ * @property {V1Filter | undefined} [where] Filter using the current query grammar; projection is unsupported.
+ * @property {string | undefined} [offset] -1 (default, server bootstrap only), snap.<head>.<base64url-id>, or a decimal log position.
+ * @property {string | undefined} [handle] Required after bootstrap.
+ * @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 offset: string; readonly ops: readonly V1ShapeOp[] }} V1ShapeChange */
+/**
+ * One snapshot page or log chunk. Only a fresh open tail/live response can report upToDate.
+ * @typedef {object} V1ShapePage
+ * @property {string} shapeId
+ * @property {string} handle
+ * @property {string} offset
+ * @property {string} nextOffset
+ * @property {boolean} upToDate
+ * @property {readonly V1ShapeChange[]} changes Apply commits and operations in their received order.
+ * @property {string | undefined} cursor Echo this as cursor on the next live request.
+ * @property {string | undefined} etag
+ */
+const maximumOffset = (1n << 63n) - 1n;
+const handlePattern = /^h1-[0-9a-f]{16}$/u;
+/** @param {unknown} value @returns {boolean} */
+function isLogOffset(value) {
+  const parsed = parseU64(value);
+  return parsed !== undefined && parsed <= maximumOffset;
+}
+/**
+ * Validates canonical C# offsets. Snapshot positions use a UTF-8/base64url keyset, not a page number.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function requireShapeOffset(value) {
+  if (value === "-1" || isLogOffset(value)) return /** @type {string} */ (value);
+  if (typeof value !== "string") throw new TypeError("A shape offset is a string.");
+  const match = /^snap\.([0-9]+)\.(0|[A-Za-z0-9_-]{2,})$/u.exec(value);
+  if (match !== null && isLogOffset(match[1])) {
+    const encoded = match[2] ?? "";
+    if (encoded === "0") return value;
+    try {
+      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;
+    } 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>.");
+}
+/** @param {unknown} value @returns {string} */
+function requireHandle(value) {
+  if (typeof value !== "string" || !handlePattern.test(value)) throw new TypeError("A shape handle is h1- followed by 16 lowercase hex characters.");
+  return value;
+}
+/** @param {V1ShapeRequest} request @returns {URLSearchParams} */
+export function encodeShapeRequest(request) {
+  if (typeof request !== "object" || request === null || Array.isArray(request)) throw new TypeError("A shape request is an object.");
+  for (const key of Object.keys(request))
+    if (!["where", "offset", "handle", "live", "cursor"].includes(key)) throw new TypeError(`Unknown shape member ${key}.`);
+  const query = new URLSearchParams();
+  if (request.where !== undefined) query.set("where", stringifyExactJson(requireFilter(request.where), "shape filter"));
+  const offset = requireShapeOffset(request.offset ?? "-1");
+  query.set("offset", offset);
+  if (request.handle !== undefined) query.set("handle", requireHandle(request.handle));
+  else if (offset !== "-1") throw new TypeError("A shape handle is required after bootstrap.");
+  if (request.live !== undefined && typeof request.live !== "boolean") throw new TypeError("live is a boolean.");
+  if (request.live === true) {
+    if (!isLogOffset(offset)) throw new TypeError("live requires a log offset.");
+    query.set("live", "true");
+  }
+  if (request.cursor !== undefined) {
+    if (request.live !== true || !isLogOffset(request.cursor) || BigInt(request.cursor) === maximumOffset)
+      throw new TypeError("cursor requires live=true and a decimal below Int64.MaxValue.");
+    query.set("cursor", request.cursor);
+  }
+  return query;
+}
+/** @param {JsonValue | undefined} value @param {Headers} headers @returns {V1ShapePage} */
+export function decodeShapePage(value, headers) {
+  const raw = object(value, "shape page");
+  const shapeId = string(raw.shape_id, "shape_id");
+  if (!/^[0-9a-f]{32}$/u.test(shapeId)) malformed("shape_id");
+  const cursor = headers.get("tb-shape-cursor") ?? undefined;
+  if (cursor !== undefined && !isLogOffset(cursor)) malformed("shape cursor");
+  return Object.freeze({
+    shapeId, handle: requireHandle(raw.handle),
+    offset: requireShapeOffset(raw.offset), nextOffset: requireShapeOffset(raw.next_offset),
+    upToDate: boolean(raw.up_to_date, "shape up_to_date"), cursor,
+    etag: headers.get("etag") ?? undefined,
+    changes: Object.freeze(array(raw.changes, "shape changes").map(value => {
+      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");
+        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") });
+      })) });
+    })),
+  });
+}
+/**
+ * Bootstrap extracts continuation metadata from 307 but never forwards credentials to Location.
+ * The next request is rebuilt against the same named route and configured endpoint.
+ * @param {V1Transport} transport
+ * @param {Readonly<Record<string, string>>} params
+ * @param {V1ShapeRequest} request
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<V1ShapePage>}
+ */
+export async function readShape(transport, params, request, signal) {
+  const query = encodeShapeRequest(request);
+  let response = await transport.call("readShape", params, { query, signal });
+  if (response.status === 307) {
+    if (query.get("offset") !== "-1") malformed("unexpected shape redirect");
+    const source = new URL(await transport.url("readShape", params, signal));
+    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");
+    const handle = requireHandle(target.searchParams.get("handle"));
+    const offset = requireShapeOffset(target.searchParams.get("offset"));
+    if (!offset.startsWith("snap.")) malformed("shape bootstrap offset");
+    query.set("handle", handle);
+    query.set("offset", offset);
+    response = await transport.call("readShape", params, { query, signal });
+    if (response.status !== 200) malformed("repeated shape redirect");
+  }
+  const page = decodeShapePage(response.value, response.headers);
+  if (page.offset !== query.get("offset") || (query.has("handle") && page.handle !== query.get("handle"))) malformed("shape response position");
+  return page;
+}