@terrascale/sdk 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.0.11 — read replica isolation and freshness
+
+Persisted shape replicas bind to their service, project, database, collection and
+filter. Authorization denial clears local documents and freshness; transient
+disconnection marks the view stale while retrying the same checkpoint. Closing
+a subscription settles even when a replica store never finishes loading or saving.
+
+## 0.0.10 — production contract fixes
+
+The named hosted-auth token operation accepts explicit project API-key grants
+without a resource parameter. Public health probes accept omitted private build
+metadata. Hosted-auth operations return authentication denials without replaying
+requests with a changed credential. README qualification commands follow the
+binary-free HTTP test policy and document the existing TypeScript model tooling.
+
 ## 0.0.9 — declared JSON Schema models
 
 Node tooling at `@terrascale/sdk/codegen` generates document, create and

package/README.md

@@ -1,7 +1,7 @@
 # @terrascale/sdk
 
 The JavaScript/JSDoc SDK for the project-scoped C#/.NET TerraBase server
-(`TerraScale/terrascale`). Current source compatibility is pinned at
+(`TerraScale/terrascale`). The historical source compatibility audit records
 `e30ffdc287530551b161b0130220be53d3c0475e`; see the
 [compatibility audit](docs/api-compatibility-20261013.md) for exact evidence and open gates.
 The package targets Node.js 22 and 24 and current Chrome, Firefox, Safari, and Edge.
@@ -100,8 +100,8 @@ to TS-507; this release requires an explicit URL or caller-supplied resolver.
 
 Current handler source implements project-scoped database names and point
 addresses as `/documents/by-key?id=…`. The complete method/path/scope inventory
-is in [sdk-v1-route-manifest.json](sdk-v1-route-manifest.json), with 25 current
-source-backed routes and one retained historical shape route. Current generated
+is in [sdk-v1-route-manifest.json](sdk-v1-route-manifest.json), including the
+current public inventory and a retained historical shape route. Current generated
 OpenAPI and immutable release qualification remain open gates.
 
 | Surface | Public methods |
@@ -257,9 +257,9 @@ for await (const row of db.export({ after: last, signal: controller.signal })) {
 }
 ```
 
-The exported collection `shape()` remains compatible with the historical
-`6cb9745…` release. Its route is absent from the audited current server source;
-do not use it as current producer evidence. SSE changes are a separate database
+The exported collection `shape()` reads the current free shape protocol using
+`documents:read`. A retained historical `shapes:read` route descriptor does not
+qualify that current protocol. SSE changes are a separate database
 feed, not authorized bounded-query snapshots or the planned reactive WebSocket API.
 
 ## Free shape subscriptions (protocol v1)
@@ -354,12 +354,13 @@ in either runtime.
 This implements the [proposed protocol](contracts/shape-v1/shape-reads.md) at
 `993927ce7ecf8f9b889d24d4d1d21ec96eaf9416`, using `documents:read`. HTTP fakes and the
 upstream [conformance vectors](test/fixtures/shape-vectors.json) verify client
-behavior; they do not qualify a producer deployment. Current generated OpenAPI,
-live endpoint availability, and automatic region discovery remain unqualified.
-No TerraBase binary is downloaded or run by these tests. The existing historical
-`shape()` method keeps its contract. Manifest/object delivery and 302 redirects
-are deferred to FR-22; vector `presigned-manifest` is explicitly skipped until its
-delivery contract is ready upstream.
+behavior; they do not qualify a producer deployment. Isolated production checks
+on 2026-10-26 verified shape bootstrap, continuation, manifest and epoch-key reads,
+live subscription updates, and checkpoint restore. Full current generated
+OpenAPI and semantic-corpus parity, sealed-object delivery/decryption, and
+automatic region discovery remain open qualification gates. These collection
+reads do not implement the planned bounded-query WebSocket result protocol.
+No TerraBase binary is downloaded or run by SDK tests.
 
 Failures throw `TerraBaseV1Error` with status, code, optional transaction `op`,
 parsed `body`, raw `responseText`, response `headers`, and a received
@@ -376,44 +377,22 @@ failing in this draft. See the audit for exact results and producer dependencies
 ## Ouroboros and qualification
 
 Ouroboros means TerraScale services store their data in the same production
-TerraBase that customers use. SDK boundary tests must run the real C# TerraBase
-release binary, pinned by immutable version and SHA-256, with an isolated
-allocation. A fixture, mocked transport, SQLite SDK runtime, frozen Rust
-contract archive or typed build cannot establish producer compatibility.
-
-The v1 route manifest and producer contract evidence must agree with the C#
-release under test. Keep live tests environment-gated; report missing local
-configuration as skipped, never as successful integration evidence. Required
-release qualification must supply the verified binary and real producer inputs.
-Never commit keys, cookies, environment files or real tenant data.
-
-The immutable release pin is
-[`scripts/ci/terrabase-release.json`](scripts/ci/terrabase-release.json): C#
-TerraBase 0.1.0, release `ci-6cb97456b9b52a92a61856601cc025c4f2833518-run-16729`,
-with binary SHA-256
-`cc2db35b18c385c6d58036c6c94e59460b0e12b0d5616da2222713efbe666700`.
-This official prerelease contains the qualified TS-754 ULID producer, the renamed
-`TerraBase` assembly and `src/TerraBase` sources. Its asset name remains `terrabase-linux-amd64`.
-The SDK integration harness consumes its official asset read-only when the
-version, source revision, size and SHA-256 are verified.
-The acquisition script verifies the official release, revision, asset size and
-digest. Private downloads require `FORGEJO_TOKEN`. Missing or mismatched official
-assets block qualification rather than selecting older bytes.
-
-```sh
-nice -n 19 npm run provision:terrabase
-export TERRABASE_BINARY=/absolute/path/printed/by/the/provisioner
-nice -n 19 npm run test:integration
-```
-
-The integration runner rechecks the binary digest, starts an isolated TLS server,
-verifies its version and runtime OpenAPI digest, and provisions a disposable
-organization, project, database, collections and scoped keys. It supplies the
-`TB_V1_*` environment and trusted local certificate to the real-server tests and
-cleans up the process and allocation afterwards. No TLS validation is disabled.
-Direct live test configuration uses `TB_V1_URL`, `TB_V1_PROJECT`,
-`TB_V1_DATA_KEY` and optionally `TB_V1_DATABASE` (default `app`);
-`TB_V1_REQUIRED=1` makes absent integration inputs fail rather than skip.
+TerraBase that customers use. Qualification requires an authorized, isolated
+real-service allocation, independently verified producer release provenance,
+and current generated-contract and route-manifest parity. HTTP fakes, local
+SQLite, historical contract inputs and typed builds cannot establish deployed
+producer compatibility.
+
+This SDK repository does not download or launch a TerraBase binary. The
+historical [release pin](scripts/ci/terrabase-release.json) does not qualify the
+current producer or JWT authorization. Keep real HTTP tests environment-gated;
+missing live configuration is skipped, never successful integration evidence.
+
+Existing live tests consume `TB_V1_URL`, `TB_V1_PROJECT`, `TB_V1_DATA_KEY` and
+optionally `TB_V1_DATABASE` (default `app`) from an independently provisioned
+allocation. Denial checks use `TB_V1_READ_KEY` and `TB_V1_WRITE_KEY`. Supply
+credentials privately; never commit keys, cookies, environment files or real
+tenant data. Local checks below do not substitute for this live gate.
 
 Local checks run at low CPU priority:
 
@@ -429,6 +408,24 @@ nice -n 19 npm test
 without adding a linter dependency. CI runs these commands at normal priority.
 See [CHANGELOG.md](CHANGELOG.md) for the 0.0.1 migration and breaking changes.
 
+## TypeScript document models
+
+Node-only `@terrascale/sdk/codegen` generates body aliases from declared JSON
+Schema, using `generateDocumentModels(schema, "Order")` or the authorized
+`generateCollectionModels(collection, "Order", { signal })` operation.
+Install its exact tooling peer separately:
+
+```sh
+npm install --save-dev json-schema-to-typescript@16.0.0
+npx terrascale-models schema.json Order models.ts
+```
+
+The input is the schema itself, without the API response wrapper. Output has
+`OrderDocument`, `OrderCreate` and `OrderPatch`; keep codegen out of browser
+bundles. Generated aliases do not validate or automatically narrow SDK reads.
+See [TypeScript document models](https://docs.terrascale.tech/guides/schema-validation#generate-typescript-document-models)
+for the supported subset, merge-patch null semantics and strict compiler setup.
+
 ## Separate and deprecated entrypoints
 
 `@terrascale/sdk/ts-auth` retains its separate hosted identity management and OIDC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",

package/src/http.js

@@ -75,9 +75,6 @@ export class TsAuthHttp {
           ? JSON.stringify(options.body)
           : options.formBody?.toString();
       let attempt = 0;
-      let refreshed = false;
-      /** @type {string | undefined} */
-      let refreshedToken;
       while (true) {
         signal?.throwIfAborted();
         let responseReceived = false;
@@ -87,11 +84,10 @@ export class TsAuthHttp {
           const oidc = options.routeName.startsWith("tsauth.oidc.");
           const token = oidc
             ? undefined
-            : (refreshedToken ??
-              (await withCancellation(
+            : await withCancellation(
                 resolveAccessToken(this.#accessToken),
                 signal,
-              )));
+              );
           if (token !== undefined && token.length > 0)
             headers.set(
               "authorization",
@@ -133,19 +129,31 @@ export class TsAuthHttp {
                 ? "application/json"
                 : "application/x-www-form-urlencoded",
             );
+          /** @type {RequestInit & { duplex?: "half" }} */
+          const init = {
+            method: options.method,
+            headers,
+            redirect: "manual",
+            ...(signal === undefined ? {} : { signal }),
+            ...(body === undefined ? {} : { body }),
+          };
+          if (options.method !== "GET" && typeof process !== "undefined" && process.release?.name === "node") {
+            // Native Node fetch replays buffered mutations on 421, even with SDK retries disabled.
+            // Empty DELETEs also need a one-shot body. Keep JSON/form bytes and media types unchanged.
+            const bytes = body === undefined ? undefined : new TextEncoder().encode(body);
+            init.body = new ReadableStream({ start(controller) {
+              if (bytes !== undefined && bytes.byteLength > 0) controller.enqueue(bytes);
+              controller.close();
+            } });
+            init.duplex = "half";
+          }
           const request = new Request(
             buildUrl(
               this.config.apiBaseUrl,
               options.path,
               options.query,
             ),
-            {
-              method: options.method,
-              headers,
-              redirect: "manual",
-              ...(signal === undefined ? {} : { signal }),
-              ...(body === undefined ? {} : { body }),
-            },
+            init,
           );
           signal?.throwIfAborted();
           fetchStarted = true;
@@ -206,22 +214,6 @@ export class TsAuthHttp {
               /** @type {TResponse} */ (parsed.value),
             );
           }
-          if (
-            response.status === 401 &&
-            !oidc &&
-            !refreshed &&
-            typeof this.#accessToken === "function"
-          ) {
-            const next = await withCancellation(
-              resolveAccessToken(this.#accessToken),
-              signal,
-            );
-            if (next !== undefined && next.length > 0 && next !== token) {
-              refreshed = true;
-              refreshedToken = next;
-              continue;
-            }
-          }
           if (
             options.method === "GET" &&
             attempt < this.config.maxRetryAttempts &&

package/src/index.js

@@ -1,6 +1,6 @@
 export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient } from "./v1/terrabase-v1.js";
 export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
-// Project-scoped TerraBase API; shape support is retained for the historical release.
+// Project-scoped TerraBase API, including current free collection shape reads.
 export {
   createTerraBaseV1Client,
   TerraBaseV1Client,

package/src/ts-auth.js

@@ -2086,6 +2086,13 @@ export class TsAuthInstanceClient {
  *       readonly grant_type: "client_credentials";
  *       readonly scope: string;
  *       readonly resource: string;
+ *       readonly project?: never;
+ *     }
+ *   | {
+ *       readonly grant_type: "client_credentials";
+ *       readonly project: import("./ids.js").EntityId;
+ *       readonly scope?: string | undefined;
+ *       readonly resource?: never;
  *     }
  *   | {
  *       readonly grant_type: "urn:ietf:params:oauth:grant-type:device_code";
@@ -2245,6 +2252,8 @@ export class TsAuthOidcClient {
 
   /**
    * client_secret_post only. Omitted resource retains the stored code/device/refresh binding.
+   * Platform API keys use explicit project and optional subset scope, without resource
+   * (producer PlatformGrants.ApiKeyAsync and platform-api.openapi.yaml ClientCredentialsGrant).
    * @param {string} clientId
    * @param {string} clientSecret
    * @param {TsAuthOidcTokenRequest} request
@@ -2259,7 +2268,7 @@ export class TsAuthOidcClient {
         : request.grant_type === "refresh_token"
           ? ["grant_type", "refresh_token", "scope", "resource"]
           : request.grant_type === "client_credentials"
-            ? ["grant_type", "scope", "resource"]
+            ? ["grant_type", "scope", "project" in request ? "project" : "resource"]
             : request.grant_type ===
                 "urn:ietf:params:oauth:grant-type:device_code"
               ? ["grant_type", "device_code", "resource"]
@@ -2289,13 +2298,24 @@ export class TsAuthOidcClient {
       if (request.scope !== undefined)
         form.set("scope", requireOauthScope(request.scope));
     } else if (request.grant_type === "client_credentials") {
-      form.set("resource", requireResourceAudience(request.resource));
-      form.set("scope", requireOauthScope(request.scope));
+      if ("project" in request) {
+        form.set("project", requireId(request.project, "project"));
+        if (request.scope !== undefined) form.set("scope", requireOauthScope(request.scope));
+      } else {
+        form.set("resource", requireResourceAudience(request.resource));
+        form.set("scope", requireOauthScope(request.scope));
+      }
     } else {
       form.set("device_code", requireText(request.device_code, "device_code"));
     }
+    const projectScope = request.grant_type === "client_credentials" && "project" in request ? request.scope : undefined;
+    const pending = this.#postForm(`${this.#slug}/oauth/token`, "tsauth.oidc.token", form);
     return oauthResponse(
-      this.#postForm(`${this.#slug}/oauth/token`, "tsauth.oidc.token", form),
+      // TokenBody follows RFC 6749 §5.1: omitted scope equals the explicit requested scope.
+      // Snapshot it before dispatch; never infer a default or normalize other grant contracts.
+      projectScope === undefined ? pending : pending.then(result =>
+        result.ok && oauthRecord(result.value) && !Object.hasOwn(result.value, "scope")
+          ? { ...result, value: { ...result.value, scope: projectScope } } : result),
       /** @returns {value is TsAuthOidcTokenResponse} */
       (value) => isTokenResponse(value, grantType),
     );

package/src/v1/shape-subscription.js

@@ -51,6 +51,15 @@ function deepFreeze(value) {
 }
 // setTimeout overflows above 2^31-1 ms and fires at once, so a long Retry-After is waited in chunks.
 const maximumTimerMilliseconds = 2 ** 31 - 1;
+/** @template T @param {T | PromiseLike<T>} operation @param {AbortSignal} signal @returns {Promise<T>} */
+function waitForStore(operation, signal) {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+    signal.addEventListener("abort", abort, { once: true });
+    void Promise.resolve(operation).then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
 /** @param {number} milliseconds @param {AbortSignal} signal @returns {Promise<void>} */
 function sleep(milliseconds, signal) {
   return new Promise((resolve, reject) => {
@@ -92,7 +101,7 @@ export class V1ShapeSubscription {
   #onUpdate;
   #replica;
   /** @type {string} */
-  #scope;
+  #scope = "";
   #external;
   #onExternalAbort = () => this.close();
   #done;
@@ -117,8 +126,6 @@ export class V1ShapeSubscription {
     this.#where = where === undefined ? undefined : requireFilter(parseExactJson(stringifyExactJson(requireFilter(where), "shape filter")));
     this.#onUpdate = onUpdate;
     this.#replica = replica;
-    // A replica restores only the identical shape it was saved from.
-    this.#scope = stringifyExactJson([this.#params.database, this.#params.collection, this.#where ?? null], "shape scope");
     this.#external = signal;
     if (signal?.aborted === true) this.close();
     else signal?.addEventListener("abort", this.#onExternalAbort);
@@ -136,11 +143,15 @@ export class V1ShapeSubscription {
   async #run() {
     const signal = this.#controller.signal;
     let retries = 0;
+    /** @type {import("./shapes.js").V1ShapeRequest | undefined} */
+    let retryRequest;
     try {
+      // Bind persisted authorization views to the service and project as well as the shape.
+      this.#scope = stringifyExactJson([await this.#transport.url("readFreeShape", this.#params, signal), this.#where ?? null], "shape scope");
       if (this.#replica !== undefined) await this.#restore(signal);
       for (;;) {
         signal.throwIfAborted();
-        const request = this.#request();
+        const request = retryRequest ?? this.#request();
         let page;
         try {
           page = await readShapePage(this.#transport, this.#params, request, signal);
@@ -148,16 +159,28 @@ export class V1ShapeSubscription {
           // Shape reads are replay-safe GETs: a lost connection keeps state and resumes at the same position.
           const lost = error instanceof RequestTransportError || error instanceof BodyTransportError;
           if (lost || (error instanceof TerraBaseV1Error && isRetryable(error))) {
+            retryRequest = request;
+            if (this.#upToDate) { this.#upToDate = false; this.#onUpdate?.(this); }
             retries = Math.min(retries + 1, maximumBackoffAttempt);
             await sleep(retryDelay(retries, lost ? undefined : error.retryAfter), signal);
             continue;
           }
+          retryRequest = undefined;
           if (!(error instanceof TerraBaseV1Error)) throw error;
+          if (error.status === 401 || error.status === 403) {
+            // Denial takes precedence over callback/storage failures. A stuck store
+            // cannot postpone the terminal auth error after local state is cleared.
+            try { this.#reset(); } catch { /* preserve the authorization failure */ }
+            try { void Promise.resolve(this.#replica?.save(undefined)).catch(() => {}); }
+            catch { /* a synchronous store failure must not mask denial either */ }
+            throw error;
+          }
           if (error.status !== 409 || error.code !== "must_refetch") throw error;
           this.#recover(request, error);
-          if (this.#handle === undefined) await this.#replica?.save(undefined);
+          if (this.#handle === undefined) await waitForStore(this.#replica?.save(undefined), signal);
           continue;
         }
+        retryRequest = undefined;
         retries = 0;
         this.#commit(page);
         await this.#persist(signal);
@@ -212,7 +235,8 @@ export class V1ShapeSubscription {
   }
   /** @param {AbortSignal} signal */
   async #restore(signal) {
-    const text = await this.#replica?.load();
+    signal.throwIfAborted();
+    const text = await waitForStore(this.#replica?.load(), signal);
     signal.throwIfAborted();
     if (text === undefined) return;
     /** @type {any} */
@@ -236,8 +260,9 @@ export class V1ShapeSubscription {
   async #persist(signal) {
     // Snapshot pages are not resumable positions; keep the previous replica until the snapshot completes.
     if (this.#replica === undefined || this.#handle === undefined || this.#offset.startsWith("snap.")) return;
-    await this.#replica.save(stringifyExactJson({ format: 1, scope: this.#scope, handle: this.#handle, offset: this.#offset,
-      cursor: this.#cursor ?? null, resume: this.#resume ?? null, documents: [...this.#documents] }, "shape replica"));
+    signal.throwIfAborted();
+    await waitForStore(this.#replica.save(stringifyExactJson({ format: 1, scope: this.#scope, handle: this.#handle, offset: this.#offset,
+      cursor: this.#cursor ?? null, resume: this.#resume ?? null, documents: [...this.#documents] }, "shape replica")), signal);
     signal.throwIfAborted();
   }
   /** @param {import("./shapes.js").V1ShapePage} page */

package/src/v1/system.js

@@ -1,12 +1,14 @@
 import { decodeDocument } from "./decode.js";
 import { requireId } from "../ids.js";
 import { requireDocumentId, requireName } from "./ids.js";
-import { flag, list, nullable, numeric, record, text } from "./management-decode.js";
+import { flag, list, nullable, numeric, optional, record, text } from "./management-decode.js";
 import { members } from "./management-validation.js";
 import { decodeCollection, decodeQueryPage } from "./terrabase-v1.js";
 import { V1Transport } from "./transport.js";
 /** @import { V1RequestOptions } from "./terrabase-v1.js" */
-const status = record({ status: text, version: text, region: text, storageFormat: text, revision: nullable(text), machine: text });
+// Public probes omit build metadata; only the internal listener emits it.
+const status = record({ status: text, version: text, region: text,
+  storageFormat: optional(nullable(text)), revision: optional(nullable(text)), machine: optional(nullable(text)) });
 const replication = record({ region: text, status: text, maxLagSeconds: nullable(numeric),
   peers: list(record({ region: text, status: text, lagSeconds: nullable(numeric) })) });
 const databases = record({ items: list(record({ name: text, id: requireId, homeRegion: text, replicaRegions: list(text), allRegions: flag })) });

package/types/ts-auth.d.ts

@@ -1103,6 +1103,13 @@ export class TsAuthInstanceClient {
  *       readonly grant_type: "client_credentials";
  *       readonly scope: string;
  *       readonly resource: string;
+ *       readonly project?: never;
+ *     }
+ *   | {
+ *       readonly grant_type: "client_credentials";
+ *       readonly project: import("./ids.js").EntityId;
+ *       readonly scope?: string | undefined;
+ *       readonly resource?: never;
  *     }
  *   | {
  *       readonly grant_type: "urn:ietf:params:oauth:grant-type:device_code";
@@ -1206,6 +1213,8 @@ export class TsAuthOidcClient {
     deviceAuthorization(clientId: string, clientSecret: string, request?: TsAuthOidcDeviceAuthorizationRequest): Promise<TerraScaleResult<TsAuthOidcDeviceAuthorizationResponse>>;
     /**
      * client_secret_post only. Omitted resource retains the stored code/device/refresh binding.
+     * Platform API keys use explicit project and optional subset scope, without resource
+     * (producer PlatformGrants.ApiKeyAsync and platform-api.openapi.yaml ClientCredentialsGrant).
      * @param {string} clientId
      * @param {string} clientSecret
      * @param {TsAuthOidcTokenRequest} request
@@ -1766,6 +1775,12 @@ export type TsAuthOidcTokenRequest = {
     readonly grant_type: "client_credentials";
     readonly scope: string;
     readonly resource: string;
+    readonly project?: never;
+} | {
+    readonly grant_type: "client_credentials";
+    readonly project: import("./ids.js").EntityId;
+    readonly scope?: string | undefined;
+    readonly resource?: never;
 } | {
     readonly grant_type: "urn:ietf:params:oauth:grant-type:device_code";
     readonly device_code: string;

package/types/v1/system.d.ts

@@ -59,9 +59,9 @@ declare const status: import("./management-decode.js").Decoder<Readonly<{
     status: string;
     version: string;
     region: string;
-    storageFormat: string;
-    revision: string | null;
-    machine: string;
+    storageFormat: string | null | undefined;
+    revision: string | null | undefined;
+    machine: string | null | undefined;
 }>>;
 declare const replication: import("./management-decode.js").Decoder<Readonly<{
     region: string;