@abloatai/ablo 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # Changelog
 
+## 0.53.0
+
+### A collection read says where the collection ends
+
+`list` returns a page. The result is still an array, so it maps, spreads, and
+iterates exactly as before, and it now carries `hasMore` and `nextCursor` beside
+the rows. Pass `nextCursor` back as `cursor`, keeping `where` and `orderBy` the
+same, to walk the rest:
+
+```ts
+let cursor: string | null = null;
+const open = [];
+do {
+  const page = await ablo.weatherReports.list({
+    where: { status: ['draft', 'review'] },
+    orderBy: { createdAt: 'asc' },
+    limit: 100,
+    ...(cursor ? { cursor } : {}),
+  });
+  open.push(...page);
+  cursor = page.hasMore ? page.nextCursor : null;
+} while (cursor);
+```
+
+A list read has always been a page: the server applies a default size and caps
+the largest one. Until now that page state was dropped on arrival, so a read
+that returned twenty of five hundred matching rows looked exactly like a
+complete one. Check `hasMore` before treating a result as the whole set.
+
+The live client keeps a local graph and loads a working set rather than pages, so
+it rejects `cursor` instead of returning the first page again. Narrow the
+`where`, or construct the client with `transport: 'http'` to page. On the live
+client `hasMore` reports whether a `limit` cut the working set short, and
+`nextCursor` is `null`.
+
+`GET /v1/projects` returns the same list envelope as every other collection,
+with `has_more` and `next_cursor` beside `data`.
+
+### The page cursor is called `cursor`
+
+The parameter that resumes a collection is `cursor`, in the SDK and on every
+HTTP collection route. It was `starting_after`, a spelling whose established
+meaning elsewhere is a row id, while this value has always been an opaque token
+tied to the sort it was issued for. A caller who read the familiar name and
+passed a row id was refused, so the name promised something it never did.
+
+`starting_after` is still accepted on the wire and is removed in a later
+release. Requests that send it keep working; new code should send `cursor`.
+Sending both uses `cursor`. The MCP `list_records` tool and the OpenAPI
+description take `cursor`, and the spec marks the old name deprecated.
+
+### A filter reaches the server intact
+
+`where` accepts operators as well as equality. An array value is an `IN`, and
+tuple form spells the rest out:
+
+```ts
+const storms = await ablo.weatherReports.list({
+  where: [
+    ['title', 'ILIKE', '%storm%'],
+    ['createdAt', '>=', cutoff],
+    ['status', 'IN', ['draft', 'review']],
+  ],
+});
+```
+
+Clauses combine with AND. For OR, run two reads and union the results.
+
+On the stateless client (`transport: 'http'`) an `IN` filter and every
+tuple-form clause were previously discarded before the request left, and the
+read came back unfiltered. An agent or worker that filtered a collection over
+HTTP was reading more rows than it asked for, with nothing to indicate it. Every
+transport now encodes a filter the same way.
+
+A filter on a boolean field could also match the opposite rows rather than fail,
+when its value arrived as the database's own text spelling. Boolean values are
+coerced before binding, and read back the same way.
+
+### A number field reads back as a number
+
+A field declared as a number arrives as one whatever integer width its column
+uses. A wide column previously came back as a decimal string while its narrower
+neighbour came back as a number, so the type a caller received depended on a
+database detail the schema had already settled.
+
+A stored value beyond the range a JavaScript number represents exactly now fails
+with `column_value_out_of_range` rather than arriving quietly rounded. Declare
+such a field as text to read those values digit for digit.
+
+### A reconnect cannot roll back a confirmed write
+
+Each row in the live client records the log position it reflects. A bootstrap or
+an on-demand read from an earlier position is left unapplied, so a snapshot that
+arrives late no longer overwrites a row the client already knows to be newer.
+The ordered change stream continues to carry every other writer's edits. A
+plugin receives that position as `syncId` on `AppliedChange`.
+
+### The base URL is checked where the credential travels
+
+`baseURL` accepts an HTTPS origin, preserving a path prefix for a deployment
+mounted under one, and plain HTTP for localhost. A URL that embeds its own
+credentials, or carries a query or a fragment, is refused when the client is
+constructed rather than failing later as an opaque request error. Every request
+attaches the resolved key against this origin, so the rule lives beside the
+option rather than in each application that sets it.
+
+`normalizeAbloHostedBaseUrl` is now `normalizeAbloBaseUrl`. The old name
+resolves to the same function and is removed in 0.54.0.
+
+### Two error codes added
+
+`organization_disabled` is returned when an operator has disabled an
+organization, and `query_relation_expansion_too_large` when a requested relation
+expansion exceeds the nested-row budget. The error contract version is
+`2026-08-15`.
+
+### CLI
+
+Where a command sends a management key is resolved and checked in one place: an
+explicit `--url` on the commands that take one, then `ABLO_API_URL`, then the
+hosted default. A host given without a scheme becomes absolute, and a
+destination that would put the key on the wire in clear, or one carrying its own
+credentials, is refused before the request is made.
+
 ## 0.52.0
 
 ### Models carry only `id`

package/docs/api.md

@@ -67,7 +67,7 @@ fallback removed — nothing to await, so they return a value.
 | Method | Returns | Use when |
 |---|---|---|
 | `get({ id })` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
-| `list({ where })` | `Promise<T[]>` | You need to hydrate a collection from local store and server. |
+| `list({ where })` | `Promise<ModelList<T>>` | You need to hydrate a collection from local store and server. |
 | `local.get(id)` | `T \| undefined` | You want a synchronous snapshot of one local row. |
 | `local.list(options?)` | `T[]` | You want a synchronous snapshot of a local collection. |
 | `local.count(options?)` | `number` | You want a synchronous count of local rows. |
@@ -79,6 +79,33 @@ fallback removed — nothing to await, so they return a value.
 through the server. The `local` reads work off the rows a session has already
 synced, so a cheap re-read needs no round-trip.
 
+### Paging a collection
+
+`list` returns a page. The result is an array, so it maps and iterates as
+before, and it carries `hasMore` and `nextCursor` alongside the rows:
+
+```ts
+let cursor: string | null = null;
+const open = [];
+do {
+  const page = await ablo.weatherReports.list({
+    where: { status: ['draft', 'review'] },
+    orderBy: { createdAt: 'asc' },
+    limit: 100,
+    ...(cursor ? { cursor } : {}),
+  });
+  open.push(...page);
+  cursor = page.hasMore ? page.nextCursor : null;
+} while (cursor);
+```
+
+Keep `where` and `orderBy` the same across pages: the cursor encodes the sort
+position it was issued for, and a read that changes either starts a new walk.
+
+`where` accepts operators as well as equality, and both travel to the server:
+`{ status: ['draft', 'review'] }` is an `IN`, and tuple form spells the rest
+out, as in `[['title', 'ILIKE', '%storm%'], ['createdAt', '>=', cutoff]]`.
+
 ## Protected Writes
 
 Use `snapshot` when a write should reject if the row changed mid-flight:
@@ -193,7 +220,9 @@ receipt; the typed SDK turns single-model writes into their application result
 (the created or updated row, or nothing for delete). A rejected write carries an
 error `code` (e.g. `stale_context`, `intent_conflict`) to act on.
 `GET /api/v1/models/{model}` is cursor-paginated (`limit`, `order`, `order_by`,
-`starting_after`) and returns `{ data, has_more, next_cursor }`.
+`cursor`) and returns `{ data, has_more, next_cursor }`. The `starting_after`
+spelling this parameter used through 0.52.0 is still honoured, and is removed in
+a later release.
 
 `POST /api/v1/commits` remains the path for **atomic multi-op** writes (several
 operations across rows/models that must commit together) — the per-model routes

package/docs/client-behavior.md

@@ -31,7 +31,7 @@ Common options:
 |---|---|
 | `schema` | Required for typed model clients. |
 | `apiKey` | Bearer credential for trusted server runtimes. Defaults to `ABLO_API_KEY` when available. |
-| `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
+| `baseURL` | Override the hosted sync endpoint for staging or private deployments. An HTTPS origin, optionally with a path prefix; plain HTTP is accepted for localhost. Your key travels here, so a URL carrying its own credentials, a query, or a fragment is refused at construction. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `durableWrites` | Optional crash recovery for unacknowledged agent/worker writes. Independent of the default memory cache; accepts `{ store, namespace? }`. |
 | `transport` | `'websocket'` (default) is the live, stateful client: a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (the `local` reads, `onChange`, `join`) are compile errors rather than runtime gaps. |

package/examples/agent-turn.ts

@@ -30,8 +30,8 @@ try {
     reads: [record],
     idempotencyKey: commitId,
   });
-  const record = await ablo.commits.get({ id: commitId });
-  console.log({ identity: ablo.identity, commit: record });
+  const commit = await ablo.commits.get({ id: commitId });
+  console.log({ identity: ablo.identity, commit });
 } finally {
   await ablo.dispose();
 }

package/examples/lease-outlives-the-machine.ts

@@ -0,0 +1,66 @@
+/**
+ * A lease outlives the process that took it.
+ *
+ * Run in two terminals against your own project. The `holder` takes a claim
+ * and is killed without releasing it, exactly as a sandbox that is torn down
+ * mid-turn would be. The `successor`, already queued, is granted the claim when
+ * the lease lapses and reads the row as it stands then.
+ *
+ * Terminal 1: ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/lease-outlives-the-machine.ts holder
+ * Terminal 2: ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/lease-outlives-the-machine.ts successor
+ *
+ * Start the successor first, then the holder, so the queue is populated before
+ * the lease lapses.
+ */
+import { Ablo } from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+const schema = defineSchema({
+  jobs: model({
+    prompt: z.string(),
+    status: z.enum(['pending', 'complete']),
+    answer: z.string().optional(),
+  }),
+});
+
+const role = process.argv[2];
+if (role !== 'holder' && role !== 'successor') {
+  throw new Error('Pass "holder" or "successor" as the first argument');
+}
+
+const jobId = process.env.JOB_ID;
+if (!jobId) throw new Error('JOB_ID is required');
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+await ablo.ready();
+
+if (role === 'holder') {
+  // A short TTL and no heartbeat: this process takes the lease and then stops
+  // proving it is alive, which is what a machine that disappears looks like
+  // from the server's side.
+  const claim = await ablo.jobs.claim({
+    id: jobId,
+    description: 'drafting the summary',
+    ttl: '10s',
+  });
+  console.log('holder: lease taken, status is', claim.data.status);
+  console.log('holder: exiting without releasing it');
+  // Deliberately skip release and skip dispose. `process.exit` runs no
+  // cleanup, so the server never hears from this participant again.
+  process.exit(0);
+}
+
+console.log('successor: queueing behind whoever holds the lease');
+const started = Date.now();
+await using claim = await ablo.jobs.claim({
+  id: jobId,
+  description: 'taking over the draft',
+  ttl: '30s',
+  heartbeat: { every: '10s' },
+});
+console.log(`successor: granted after ${Math.round((Date.now() - started) / 1000)}s`);
+console.log('successor: read the row as it stands now —', {
+  status: claim.data.status,
+  answer: claim.data.answer,
+});
+await ablo.dispose();

package/examples/tsconfig.json

@@ -1,16 +1,10 @@
 {
+  "extends": "../tsconfig.json",
   "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "lib": ["ES2022", "DOM"],
-    "strict": true,
     "noEmit": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "types": ["node"]
+    "rootDir": "..",
+    "lib": ["ES2022", "ESNext.Disposable"]
   },
   "include": ["**/*.ts"],
-  "exclude": ["node_modules"]
+  "exclude": ["node_modules", "dist"]
 }

package/llms.txt

@@ -85,6 +85,17 @@ second verb to learn — `local.` is the only difference. The query reads accept
 and `state`; state defaults to `'live'`, with `'archived'` and `'all'` to include
 retired rows.
 
+`where` takes operators, not only equality: an array value is an `IN`
+(`{ status: ['draft', 'review'] }`), and tuple form spells the rest out
+(`[['title', 'ILIKE', '%storm%'], ['createdAt', '>=', cutoff]]`). Clauses combine
+with AND; for OR, run two reads and union them.
+
+`list` returns a page, not always the whole collection. The result is an array,
+so it maps and iterates as usual, and it carries `hasMore` and `nextCursor`
+beside the rows. Pass `nextCursor` back as `cursor`, keeping `where` and
+`orderBy` the same, to walk the rest. Check `hasMore` before treating a result
+as complete.
+
 Workers import the same app schema and select `transport: 'http'`. The transport
 changes; the typed `ablo.<model>` contract does not. There is no public
 schema-less or string-keyed model client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -112,7 +112,7 @@
     "prepack": "npm run build && node scripts/strip-source-condition.mjs",
     "postpack": "node scripts/restore-source-condition.mjs",
     "pack:check": "node scripts/pack-check.mjs",
-    "typecheck": "tsc --noEmit && tsc -p typetests/tsconfig.json",
+    "typecheck": "tsc --noEmit && tsc -p typetests/tsconfig.json && tsc -p examples/tsconfig.json",
     "test": "vitest run",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",
@@ -137,8 +137,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.52.0",
-    "@abloatai/transaction": "^0.52.0",
+    "@abloatai/humans": "^0.53.0",
+    "@abloatai/transaction": "^0.53.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {