terrascale 0.3.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## 1.0.0 — TS-498
+
+### Breaking changes
+
+1. The root entrypoint exposes only the C# TerraBase v1 client API.
+   `createTerraBaseClient` now aliases `createTerraBaseV1Client`; the retired
+   tenant/shard client, Rust discovery, schema/SQL and reactive-view
+   exports are removed from the root. Named legacy entrypoints remain separate.
+2. Client configuration requires `project`, a Bearer `tb_` token and exactly one
+   of `baseUrl` or `endpointResolver`. Tenant, shard, `apiKey`, `endpoint` and
+   `tbk1` routing assumptions no longer apply. Database operations use
+   `/v1/projects/{project}/databases/{db}` paths.
+3. Mutations follow the C# producer: `Idempotency-Key` is unsupported and writes
+   cannot be automatically replayed. Queries do not support `lower` or `explain`;
+   server numeric comparison and bounded-count semantics replace Rust assumptions.
+4. Shapes use `GET …/collections/{collection}/shape` with `shapes:read`.
+   The retired shape gatekeeper, SSE, edge tokens and projection are unavailable.
+5. `terrascale/local`, `terrascale-local` and `terrascale/postgres` are deprecated
+   legacy surfaces. SDK SQLite is no longer the required Dashboard backend;
+   real C# release binaries replace frozen Rust/fake-server qualification.
+
+### Migration
+
+Configure a provisioned project and `tb_` API key with `documents:read` and/or
+`documents:write`, then obtain `client.database(name).collection(name)` handles.
+Use `get`, `put`, `create`, `patch`, `delete` and bounded `query`/`pages`/`items`
+operations; conditional writes carry `ifMatch` or `ifNoneMatchAny`.
+Do not replay uncertain mutations without a producer deduplication contract.
+
+`staticBaseUrlResolver(baseUrl)` supplies an explicit override; a custom resolver
+receives `{ project, database }` and is resolved once per database session.
+Atlas discovery is deferred to TS-507; no regional hostname is hardcoded.
+Ouroboros qualification uses the real immutable C# TerraBase release binary,
+pinned by version and SHA-256, rather than an SDK-local substitute.
+`provision:terrabase` acquires the verified binary; `test:integration` runs it
+with isolated TLS, real tenant provisioning and runtime OpenAPI parity.
+The pinned official producer release is a draft after failed fast checks
+(terrabase #110). Its verified release asset can run SDK integration without
+publication; those results do not establish that producer source checks passed.
+
+The package and lockfile versions advance from 0.3.0 to 1.0.0. `lint` reuses the
+existing strict TypeScript/JSDoc check; dependencies are unchanged.
+
+Fresh shape bootstrap requires a server runtime; browser manual redirects hide
+the bootstrap handle and offset. Browser continuation needs those server-issued positions.

package/README.md

@@ -1,143 +1,197 @@
 # terrascale
 
-The JavaScript SDK for native TerraBase documents and hosted TerraScale identity.
+The JavaScript/JSDoc SDK for the project-scoped C#/.NET TerraBase server
+(`terrabase`, `origin/main`). Version 1.0.0 replaces the retired Rust client.
 The package targets Node.js 22 and 24 and current Chrome, Firefox, Safari, and Edge.
-Release qualification installs the exact packed artifact into a separate consumer.
-
-The source is plain ES modules typed with JSDoc and published as written; there
-is no transpile step. `npm run build` generates the `.d.ts` declarations in
-`types/`, so TypeScript and editor consumers get the same types the source is
-checked against.
+Plain ES modules ship as written; `nice -n 19 npm run build` generates the
+TypeScript declarations in `types/`.
 
 ```js
-import { createTerraBaseClient } from "terrascale";
+import { createTerraBaseV1Client, documentIdFor, v1Filter } from "terrascale";
 
-const database = createTerraBaseClient({
-  tenant: process.env.TERRABASE_TENANT,
-  database: process.env.TERRABASE_DATABASE,
-  shard: BigInt(process.env.TERRABASE_SHARD),
-  apiKey: process.env.TERRABASE_API_KEY,
+const client = createTerraBaseV1Client({
+  project: process.env.TERRABASE_PROJECT,
+  token: process.env.TERRABASE_API_KEY,
+  baseUrl: process.env.TERRABASE_BASE_URL,
 });
+const db = client.database("app");
+const todos = db.collection("todos");
+
+const id = await documentIdFor("todos", "first-task");
+await todos.put(id, { title: "Use TerraBase", done: false }, { ifNoneMatchAny: true });
+const doc = await todos.get(id);
+await todos.patch(id, { merge: { done: true } }, { ifMatch: doc.version });
 
-const result = await database.read(collectionUuid, documentUuid);
-if (!result.ok) throw new Error(result.error.code);
-console.log(result.value.state);
+for await (const page of todos.pages({ filter: v1Filter.eq("/done", true), limit: 50 })) {
+  console.log(page.items);
+}
 ```
 
-Entity IDs are canonical UUIDs. Shard, generation, sequence, and signed integer
-values remain bigint; bytes remain Uint8Array. Preserve every conflict sibling
-and the complete causal context. Missing fields are omitted; `{ type: "null" }`
-is an explicit null. Use the actual provisioned collection's numeric field IDs,
-schema generation, and digest. Schema helpers describe local declarations and
-SQL builders produce parameterized descriptors; neither provisions a catalog.
-
-Native methods are `read`, `query`, `subscription`, `prepareCommit`, `commit`,
-and `transactionStatus`. Queries use bounded typed predicates and opaque cursors.
-Subscriptions first consume a complete paginated snapshot, then finite poll
-groups. SQL execution requires the separate PostgreSQL listener contract.
-
-`createDatabaseQuery(client, options)` delivers complete native snapshot and poll
-cuts to `useQuery` from `terrascale/react` or `createQuery` from
-`terrascale/svelte`. TanStack DB 0.9.2 integration is available through
-`terrascaleCollectionOptions` from `terrascale/tanstack`; map each complete
-point explicitly and preserve conflicts. Publication is acknowledged before
-advancing delivery, and cleanup cancels owned work. Mutations prepare and commit
-through the same client; a presentation rollback does not establish a server abort.
-
-Omitting `endpoint` uses authenticated, scope-bound routing at
-`https://atlas.terrascale.tech` with the native `tbk1` database key. The client
-selects an eligible canonical regional origin and checks its bounded lease again
-before dispatch. `discoveryTimeoutMs` defaults to 3000 and accepts 1–30000 ms.
-Each operation uses the receiver's highest-priority endpoint with the required
-capabilities. Discovery denial, unavailability, invalid or expired leases, and
-missing capabilities return a typed error before any native data request.
-Set `endpoint` to use an independently provisioned direct HTTPS origin. HTTP is
-allowed only on loopback for development, and the public test host is rejected.
-Database keys and hosted identity management keys are separate credentials.
-
-The admitted Atlas receiver advertises conditional mutations, atomic groups,
-and security state as unavailable. Discovered clients refuse those operations
-before native dispatch. Direct local native conditional semantics do not grant
-those production capabilities.
-
-For authentication/security conditional writes, use the provisioned single-writer authority, including
-its generation and writer identity. An absent condition requires absence; a
-version condition compares the complete point's state token. Copy the point's
-full context into `observed` for replacement or deletion. Causal observation
-alone does not establish compare-and-swap. Direct leaderless conditional commits
-prove only the admitted local native exclusion semantics; they do not establish
-distributed writer fencing. Leaderless storage is unsuitable for
-security state and authentication invariants.
-
-`prepareCommit` snapshots the request and computes its canonical SHA-256 effect
-fingerprint. Reuse that prepared transaction on the same client for an exact
-retry; a changed effect requires a new transaction identity. Mutations are not
-automatically replayed. Resolve an uncertain mutation with transaction status;
-unknown, pending, and expired status do not establish an abort. Persist the
-transaction identity, authority, and fingerprint when recovery spans restarts.
-`local_durable` and `object_durable` are distinct acknowledgement levels.
-
-`terrascale/ts-auth` contains the separate hosted identity management and
-OIDC client. Its private transport preserves form-encoded token operations,
-bounded responses, deadlines, and a single changed-token refresh. Configure
-its own origin, instance, and identity credentials.
-
-`terrascale/local` is an explicitly enabled Node development runtime:
+Provision the project, database and collection before using their handles.
+API keys begin with `tb_` and travel as `Authorization: Bearer <key>`.
+Reads and queries require `documents:read`; writes and transactions require
+`documents:write`. Transaction assertions additionally require `documents:read`.
+Keep keys private and out of logs and browser bundles. `createTerraBaseClient`
+is an alias of `createTerraBaseV1Client`; it no longer accepts tenant/shard options.
+
+## Atlas and endpoint selection
+
+Supply exactly one of `baseUrl` or `endpointResolver`. A resolver receives
+`{ project, database }` and returns the service URL, synchronously or asynchronously.
+The URL is resolved once per database session and reused by its operations.
+Shared resolution expires after 30 seconds and supplies a cancellation signal
+to the resolver; a later operation can retry an expired or failed resolution.
+Cancelling one operation leaves other callers' shared resolution running.
+HTTPS is required except for loopback HTTP in local development; no regional
+host is hardcoded and no implicit production endpoint is selected.
 
 ```js
-import { createTerraScaleSqliteRuntime } from "terrascale/local";
+import { createTerraBaseV1Client, staticBaseUrlResolver } from "terrascale";
 
-const local = createTerraScaleSqliteRuntime({
-  sqlite: { enabled: true, databasePath: "/absolute/path/development.sqlite" },
+const client = createTerraBaseV1Client({
+  project: process.env.TERRABASE_PROJECT,
+  token: process.env.TERRABASE_API_KEY,
+  endpointResolver: staticBaseUrlResolver(process.env.TERRABASE_BASE_URL),
 });
-await local.bindCollection({
-  collection: collectionUuid,
-  schema_generation: 1n,
-  schema_digest,
-});
-const client = local.createClient();
-// Use local.authority for local conditional commits.
-await local.close();
+const db = client.database("app");
+```
+
+Atlas (`ts-atlas`, a TypeScript Cloudflare Worker) discovers the closest eligible
+region and the location of a project/database. The resolver seam allows that
+choice to stay pinned for the session. Atlas discovery integration is deferred
+to TS-507; this release requires an explicit URL or caller-supplied resolver.
+
+## Documents, queries, transactions and shapes
+
+The C# producer owns these routes:
+
+| Operation | Method and path |
+| --- | --- |
+| Documents | `GET/PUT/PATCH/DELETE /v1/projects/{project}/databases/{db}/collections/{c}/documents/{id}`; `POST …/documents` |
+| Query | `POST /v1/projects/{project}/databases/{db}/collections/{c}/query` |
+| Transaction | `POST /v1/projects/{project}/databases/{db}/transactions` |
+| Shape | `GET /v1/projects/{project}/databases/{db}/collections/{c}/shape` |
+
+Collection methods are `get`, `put`, `create`, `patch`, `delete`, `query`,
+`pages` and `items`. New document IDs are canonical UUIDs; `documentIdFor`
+generates a stable UUIDv5 from a natural key. Documents return
+`{ id, version, state: "value", document }`. Writes return the version and a
+decimal-string commit `offset`; preserve those opaque positions and use
+`ifMatch` or `ifNoneMatchAny` for conditional writes.
+
+Queries support typed filters, sorting, projection and bounded cursor pages.
+`query` returns one page; `pages` and `items` follow `nextCursor`.
+`count.exact: false` means the count is a lower bound. The current C# producer
+does not support `lower` paths or `explain`; query number comparisons use its
+64-bit integer/double arithmetic, even when the SDK preserves exact JSON numbers.
+`ExactDecimal` and bigint serialization require Node.js 22+ or a current browser.
+
+`db.transaction()` builds one bounded atomic group across collections in that
+database. It supports document operations, `assert`, `assertAbsent` and
+`assertCount`; assertions examine the state before the group's writes.
+The C# producer rejects `Idempotency-Key`. Do not enable automatic idempotency
+or replay mutations after an uncertain result; this release does not promise
+mutation deduplication. Validation, authentication, authorization and
+precondition failures are not automatically retried.
+
+Shapes require `shapes:read` and use the collection's GET route with a `where`
+filter, handle, offset and live cursor. Snapshot bootstrap and checkpoint resume
+provide correctness; `must_refetch` requires discarding local state and starting
+a fresh snapshot. The C# producer has no shape gatekeeper, SSE route, edge shape
+token or projection support. Origin responses require private cache revalidation. Fresh shape bootstrap is
+server-only in this release: browsers hide the initial 307 redirect metadata.
+Browser callers need a handle and snapshot offset obtained on their server.
+
+The same public SDK supplies this metadata on the server. Pass the position to
+the browser and repeat that immutable snapshot page with the identical filter
+and collection:
+
+```js
+// Server: use the public client with the caller's shapes:read key.
+const snapshot = await serverCollection.shape({ where });
+const position = { handle: snapshot.handle, offset: snapshot.offset };
+// Browser: resume using position supplied by your application server.
+const page = await browserCollection.shape({ where, ...position });
 ```
 
-The local runtime refuses CI, production, qualification, staging, and deployment
-environments. Its official Better Auth 1.7.2 adapter uses development SQLite
-transactions and maintained adapter suites. These checks do not qualify
-production security, regional replication, or the deployed customer application.
+Failures throw `TerraBaseV1Error` with the HTTP status and producer error code;
+transaction failures may also identify the failing `op`. Request cancellation
+uses `AbortSignal`.
+
+## 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-0248ad3ac6fb82ac900e38005840a619e5d0beac-run-13267`,
+with binary SHA-256
+`8abcedaa6b8487f08ecafe4485862f1f9309154e58ac1a74eda2278b78500968`.
+This official release is currently a draft: the producer's fast checks failed
+and publication was skipped (terrabase #110). The SDK integration harness may
+consume its official asset read-only when the version, source revision, size and
+SHA-256 are verified; publication is not required. Draft status does not establish
+that the producer's source qualification passed.
+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 management, administration, and production Better Auth entrypoints fail
-with explicit capability errors until management/catalog provisioning and
-credential lifecycle (C06/C07) and production Better Auth security persistence
-are admitted.
+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.
 
-Every push to `main` that passes CI publishes the `package.json` version to npm
-when that version is not yet published. Bump the version to release.
+Local checks run at low CPU priority:
 
 ```sh
-npm ci
-npm run typecheck
-npm run build
-npm test
-npm run check:frameworks
-npm run check:current-contract-inputs
-npm run check:current-contract
-npm run test:browser
+nice -n 19 npm ci
+nice -n 19 npm run typecheck
+nice -n 19 npm run lint
+nice -n 19 npm run build
+nice -n 19 npm test
 ```
 
-Source parity requires absolute `TERRASCALE_CURRENT_OPENAPI` and
-`TERRASCALE_ATOMIC_VECTORS` paths matching `sdk-current-contract.json` exactly.
-Run `npm run qualify:current-producer` with a supplied immutable tarball and a
-real isolated allocation; see [qualification inputs](scripts/qualification/README.md).
-Missing real-producer inputs fail the required gate. See [release requirements](docs/release.md).
+`lint` reuses the strict TypeScript/JSDoc check, including unused-code checks,
+without adding a linter dependency. CI runs these commands at normal priority.
+See [CHANGELOG.md](CHANGELOG.md) for the 1.0.0 migration and breaking changes.
+
+## Separate and deprecated entrypoints
+
+`terrascale/ts-auth` retains its separate hosted identity management and OIDC
+client, with its own origin, instance and credentials. Management,
+administration and production Better Auth capabilities remain subject to their
+explicit admission errors; they are not a shortcut into the database transport.
+
+`terrascale/local` (including `terrascale-local`) and `terrascale/postgres` are
+**deprecated legacy entrypoints**. SQLite stays opt-in for development only and
+refuses CI, production, staging, qualification and deployment environments.
+It is no longer the required Dashboard backend and does not qualify the C# API.
+The PostgreSQL listener and retired tenant/shard client are outside the default
+v1 API. Existing framework, schema and SQL entrypoints are separate legacy
+surfaces; the root entrypoint exposes the C# v1 client API.
 
 Hosted OAuth resource requests use one exact registered HTTPS `resource`. `oidc.authorizationUrl`, `oidc.deviceAuthorization`, and the code, device, refresh, and client-credentials token grants retain its bytes, including path and query. Omission on a browser code or refresh flow preserves the stored no-resource binding; it never repairs a rejected audience or falls back to browser login. Refresh requests can ask for narrower scopes. Client credentials require explicit resource and scope values. Token and originating-client introspection methods use `client_secret_post`; public-client and originating-client Basic token authentication are not currently exposed by this SDK.
 
 `oauthClients` and `oauthResources` provide the producer's snake_case policy records and named management operations. Resource PATCH requires `expected_auth_epoch`; client PATCH accepts it. JSON epochs outside JavaScript's exact integer range are rejected. Client PATCH returns a bare client view unless `rotate_secret` is true, when it returns the client and its one-time secret. Resource create/PATCH always return the resource and nullable one-time introspection secret.
 
 Use `oidc.introspectResource` with independently configured `issuer`, exact `audience`, `introspection_client_id`, and `introspection_secret`. It uses resource Basic authentication only, with each credential component form encoded before Base64. An active result requires the exact configured issuer/audience, `Bearer`, integer timestamps valid at the local clock with no default skew, and the required user/service session shape. Inactive results contain only `active: false`. Resource results expose no internal epochs, refresh family, or token-use fields. The provider checks current durable token/session/resource state; an active principal or scope does not grant project ownership or management authority. Product authorization remains at the caller's existing authorization boundary.
-
-Regional native database origins use `https://<region>.api.terrascale.tech`,
-for example `https://gru.api.terrascale.tech`. The global API host and retired
-root regional hosts cannot serve as native origins. Auth uses its separate
-`.auth.terrascale.tech` namespace. Direct independent origins must use ASCII
-hostnames; percent-encoded and Unicode hostname aliases are rejected.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "terrascale",
-  "version": "0.3.0",
-  "description": "JavaScript SDK, typed with JSDoc, for native TerraBase documents and hosted TerraScale identity.",
+  "version": "1.0.0",
+  "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",
   "private": false,
@@ -77,34 +77,29 @@
     "!src/**/*.test.js",
     "types",
     "!types/integration",
-    "sdk-route-manifest.json",
-    "sdk-current-contract.json",
+    "sdk-v1-route-manifest.json",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('types', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
-    "qualify:artifact": "node scripts/qualify-npm-artifact.js",
-    "qualify:current-producer": "node scripts/qualification/current-producer-consumer.js",
-    "check:route-manifest": "node scripts/generate-client-route-manifest.js --check",
-    "check:openapi-contract-descriptor": "node scripts/generate-openapi-contract-descriptor.js --check",
-    "check:public-contract-fixture": "vitest run test/public-contract-fixture.test.js",
+    "prepack": "npm run build",
+    "check:v1-route-manifest": "node scripts/generate-v1-route-manifest.js --check",
     "check:forbidden-surface": "vitest run test/forbidden-surface.test.js",
     "check:sbom": "node scripts/check-sbom.js",
     "check:vulnerabilities": "node scripts/check-vulnerabilities.js",
-    "generate:route-manifest": "npm run build && node scripts/generate-client-route-manifest.js",
-    "generate:openapi-contract-descriptor": "npm run build && node scripts/generate-openapi-contract-descriptor.js",
+    "generate:v1-route-manifest": "node scripts/generate-v1-route-manifest.js",
     "local": "node src/local/cli.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "npm run typecheck",
     "test": "vitest run",
+    "provision:terrabase": "node scripts/ci/provision-terrabase.mjs",
+    "test:integration": "node scripts/ci/run-terrabase-integration.mjs",
     "test:browser": "playwright test",
-    "check:current-contract": "vitest run test/current-producer-contract.test.js test/openapi-drift.test.js",
     "qualify:auth-authority": "node scripts/qualify-auth-authority.js",
-    "qualify:release-e2e": "node scripts/run-packed-release-e2e.js",
-    "check:current-contract-inputs": "node scripts/openapi-contract-paths.js --check-inputs",
     "check:frameworks": "vitest run src/database-view.test.js src/react/core.test.js src/svelte/index.test.js src/tanstack/index.test.js",
-    "check:local-better-auth": "vitest run src/better-auth-factory-conformance.test.js",
-    "qualify:current-postgres-producer": "node scripts/current-postgres-producer.js"
+    "check:local-better-auth": "vitest run src/better-auth-factory-conformance.test.js"
   },
   "peerDependencies": {
     "@better-auth/core": "1.7.2",