@abloatai/ablo 0.28.0 → 0.29.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.29.1
+
+### Patch Changes
+
+- **The `omitModels` doc example uses generic model names.** The schema-projection example in the `omitModels` JSDoc and the API docs now reads `omitModels(full, ['reports', 'reportSections'])` — an illustrative parent/child pair rather than application-specific model names. Documentation only; no API or behavior change.
+
+## 0.29.0
+
+### Minor Changes
+
+- **`omitModels()` projects a schema by exclusion — the companion to `selectModels`.** Keep every model except the named ones, so one app can be the general case while a separate app owns the models it drops. The suite shell narrows with `omitModels(full, ['reports', 'reportSections'])` while the standalone app selects those same models. Validation matches `selectModels`: relations into the omitted set are dropped, and a dropped `parent` edge throws, so a model whose scope routes through an omitted parent can't be silently kept. Each app now binds its own schema projection rather than sharing one global registration.
+
+- **Every application model has one typed access path: `ablo.<model>`.** Both the WebSocket and stateless HTTP clients return bare rows from `retrieve` and accept the same typed create/update/delete forms. The schema-less `Ablo({ schema: null })` overload, the public `.model(name)` accessors, the transport-envelope types, and the hidden capability CRUD client are removed. Select `transport: 'http'` for workers without changing model syntax, use `commits.create` only for atomic multi-row writes, and `sessions.create` to mint a scoped user or agent credential.
+
+- **The commit wire names only the protocol that actually runs.** `@abloatai/ablo/wire` exports `CommitMessage`, `MutationResultMessage`, `commitOperationSchema`, and `commitPayloadSchema` directly. The prospective v2 commit contract published under `@abloatai/ablo/commit` in 0.28.0 — its `CommitReceipt` type, the `legacyCommit*` wire aliases, and the unsent named-mutation frame — is removed, so there is one contract to implement and test. Idempotency-key sealing and fencing move to `transactions/idempotencyKey.ts` (ADR 0006: the v1/v2 boundary lives at ingress, not in the client). Local `useMutators` calls still compose normal transactions; this removes only the dead server wire path.
+
+- **Protocol support is backed by codecs, not a numeric claim (ADR 0005).** The wire package publishes an explicit supported-version manifest; the server must provide a decoder for every entry. Durable HTTP writes seal their original protocol version and replay with it after an upgrade. Application-schema hashes are an advisory bootstrap warning rather than an exact WebSocket gate, so additive schema versions can overlap through an expand/contract rollout.
+
+- **The injected write-storage option is `durableWrites`, and `DurableWriteStore` is its interface.** The `commitOutbox` client option and `CommitOutboxStore` interface introduced in 0.28.0 are renamed. `durableWritesConfigSchema`, `durableWriteStoreSchema`, `pendingWriteSchema`, and the `DurableWritesConfig` / `DurableWriteStore` / `PendingWrite` types are exported from the package root, so a workflow-, SQLite-, or filesystem-backed adapter validates against the shipped schema instead of an interface you re-declare. The old `commitOutbox` / `CommitOutboxStore` names remain as deprecated aliases through the next major release.
+
+- **`Register` registers your `Schema` and `UserMeta` — those are the two keys.** The `Presence` and `Claims` registration keys and their `ResolvePresence` / `ResolveClaims` resolver types are gone, matching the removed presence and claim React placeholders. Read presence through `usePeers` or `useWatch`, and row claims through `ablo.<model>.claim`. The default resolver now carries a `SchemaRecord` fallback, so a shared package typechecks standalone with no app registration in scope.
+
+- **One signed adapter export: `dataSource`.** The `abloSource` alias is removed, and the parallel `DataSource*` type names (`DataSourceOptions`, `DataSourceCommitParams`, `DataSourceHandlerContext`, and the rest) collapse into the canonical `Source*` types — one name per shape. Endpoints already built with `dataSource()` are unchanged; only the duplicate names are gone.
+
+- **The claim type surface is reached through `Ablo.Claim.*`.** `ClaimOptions`, `ClaimParams`, `ClaimLookupParams`, `ClaimReorderParams`, `Claim`, `ClaimHeartbeat`, `ClaimHeartbeatOptions`, and `ModelOperations` are namespace members rather than top-level exports; `HeldClaim` stays as a deprecated top-level alias because 0.20.1 documented it. The internal construction types `InternalAbloOptions` and `HttpClaimApi` are no longer exported — the public surface names only what an application builds against.
+
+### Patch Changes
+
+- **Removed React placeholders that had no working runtime.** `usePresence`, `useClaim`, `SyncGroupProvider`, and `useSyncGroup` are no longer exported. Use `usePeers` or `useWatch` for presence and scoped participation, and `ablo.<model>.claim` for row claims. The unused `Register.Presence` / `Register.Claims` resolver types are gone with them.
+
 ## 0.28.0
 
 ### Minor Changes
@@ -26,6 +56,12 @@
 
 - **Docs and error copy name the real HTTP mount.** REST paths are documented as `/api/v1/...` — the OpenAPI server URLs carry the `/api` mount — and the `jwt_issuer_untrusted` message no longer points at an endpoint that doesn't exist.
 
+- **The resume cursor advances only through the contiguous durable prefix of a delta frame.** A frame spanning several local stores commits per store, and those transactions can fail independently — taking the maximum id from any successful store could permanently skip an earlier failed delta on every later catch-up.
+
+- **Conflicting undo-scope options warn instead of being silently ignored.** A scope keeps the options it was created with; the silent version of that rule could leave a surface believing it enabled stream recording when it hadn't.
+
+- **Docs and error copy name the real HTTP mount.** REST paths are documented as `/api/v1/...` — the OpenAPI server URLs carry the `/api` mount — and the `jwt_issuer_untrusted` message no longer points at an endpoint that doesn't exist.
+
 ## 0.27.0
 
 ### Minor Changes

package/dist/Database.js

@@ -28,6 +28,9 @@ function isSameOutboxRecord(existing, candidate) {
             type: record.type,
             storageVersion: record.storageVersion,
             idempotencyKey: record.idempotencyKey,
+            // HTTP outbox rows written before protocol versioning are v1. Normalize
+            // them so a same-request re-seal remains idempotent after an upgrade.
+            protocolVersion: record.protocolVersion ?? 1,
             request: record.request,
             scopeNamespace: record.scopeNamespace,
         });
@@ -1259,14 +1262,14 @@ export class Database {
             const store = this.transactionStore;
             const existing = (await store.get(recordId));
             if (existing && !isSameOutboxRecord(existing, record)) {
-                throw new AbloValidationError('Commit outbox key already identifies a different request', {
+                throw new AbloValidationError('Pending-write key already identifies a different request', {
                     code: 'idempotency_conflict',
                 });
             }
             if (!existing) {
                 const sources = await Promise.all(consumedRecordIds.map((id) => store.get(id)));
                 if (sources.some((source) => source === undefined)) {
-                    throw new AbloValidationError('Commit outbox source mutations were already claimed by another envelope', { code: 'idempotency_conflict' });
+                    throw new AbloValidationError('Pending-write source mutations were already claimed by another write', { code: 'idempotency_conflict' });
                 }
                 await store.add(record);
             }
@@ -1278,7 +1281,7 @@ export class Database {
         }
         const db = this.workspaceDb;
         if (!db || this.isClosing) {
-            throw new AbloConnectionError('Database not opened for commit outbox', {
+            throw new AbloConnectionError('Database not opened for durable writes', {
                 code: 'db_not_opened',
             });
         }
@@ -1304,7 +1307,7 @@ export class Database {
                         return;
                     promotionStarted = true;
                     if (existing && !isSameOutboxRecord(existing, record)) {
-                        collisionError = new AbloValidationError('Commit outbox key already identifies a different request', { code: 'idempotency_conflict' });
+                        collisionError = new AbloValidationError('Pending-write key already identifies a different request', { code: 'idempotency_conflict' });
                         tx.abort();
                         return;
                     }
@@ -1314,7 +1317,7 @@ export class Database {
                     // cannot dispatch. An identical existing envelope is an idempotent
                     // retry, so its already-consumed sources may be absent.
                     if (!existing && sourceExists.some((exists) => !exists)) {
-                        collisionError = new AbloValidationError('Commit outbox source mutations were already claimed by another envelope', { code: 'idempotency_conflict' });
+                        collisionError = new AbloValidationError('Pending-write source mutations were already claimed by another write', { code: 'idempotency_conflict' });
                         tx.abort();
                         return;
                     }
@@ -1346,7 +1349,7 @@ export class Database {
                     reject(collisionError ??
                         tx.error ??
                         getRequest.error ??
-                        new Error('Commit outbox transaction aborted'));
+                        new Error('Durable-write transaction aborted'));
                 };
                 tx.onerror = () => {
                     // onabort owns rejection so the promise settles exactly once.

package/dist/SyncClient.d.ts

@@ -15,7 +15,7 @@ import { type UnconfirmedWritesMetrics } from './transactions/UnconfirmedWrites.
 import type { Database } from './Database.js';
 import type { WriteOptions } from './interfaces/index.js';
 import { SyncPosition } from './sync/syncPosition.js';
-import { type CommitOutboxStore } from './transactions/commitOutboxStore.js';
+import type { DurableWriteStore } from './transactions/durableWriteStore.js';
 interface SyncObserver {
     onSync?: (event: SyncEvent) => void;
 }
@@ -76,7 +76,7 @@ export declare class SyncClient extends EventEmitter {
      * responses, and snapshots and claims read `readFloor`.
      */
     readonly position: SyncPosition;
-    constructor(objectPool: InstanceCache, database: Database, commitOutbox?: CommitOutboxStore, commitOutboxNamespace?: string);
+    constructor(objectPool: InstanceCache, database: Database, commitOutbox?: DurableWriteStore, commitOutboxNamespace?: string);
     /**
      * Setup network monitoring handlers
      */

package/dist/SyncClient.js

@@ -1351,24 +1351,36 @@ export class SyncClient extends EventEmitter {
         // never dispatch without its durable record), so drop it rather than
         // leaving it queued to poison every later pass. Healthy batch members
         // still stage.
-        const journalResults = await Promise.allSettled(mutations.map((mutation) => mutation.journaled));
+        // Settle each mutation into an object that keeps the mutation bound to its
+        // own outcome. Correlating by array index would force a `mutations[index]!`
+        // non-null assertion (the lookup is `T | undefined` under
+        // noUncheckedIndexedAccess); carrying the reference makes it unnecessary.
+        const journalOutcomes = await Promise.all(mutations.map(async (mutation) => {
+            try {
+                await mutation.journaled;
+                return { mutation, ok: true };
+            }
+            catch (reason) {
+                return { mutation, ok: false, reason };
+            }
+        }));
         const journaledMutations = [];
-        journalResults.forEach((result, index) => {
-            const mutation = mutations[index];
-            if (result.status === 'fulfilled') {
+        for (const outcome of journalOutcomes) {
+            const { mutation } = outcome;
+            if (outcome.ok) {
                 journaledMutations.push(mutation);
-                return;
+                continue;
             }
             this.stagedMutationIds.delete(mutation.mutationId);
             this.pendingMutations = this.pendingMutations.filter((pending) => pending.mutationId !== mutation.mutationId);
-            mutation.rejectStaged?.(result.reason);
+            mutation.rejectStaged?.(outcome.reason);
             getContext().observability.captureTransactionFailure({
                 context: 'persist-pending-mutation',
-                error: result.reason instanceof Error
-                    ? result.reason
-                    : new Error(String(result.reason)),
+                error: outcome.reason instanceof Error
+                    ? outcome.reason
+                    : new Error(String(outcome.reason)),
             });
-        });
+        }
         // Stage every mutation synchronously within the same event-loop tick;
         // the transaction queue's microtask batches and sends them together.
         for (const mutation of journaledMutations) {

package/dist/adapters/inMemoryStorage.js

@@ -22,7 +22,7 @@ export class InMemoryObjectStore {
             this.indexes.set(name, new Map());
         }
     }
-    async add(record) {
+    add(record) {
         const id = record.id;
         if (!id)
             throw new TypeError('In-memory record must carry an id');
@@ -33,11 +33,12 @@ export class InMemoryObjectStore {
         }
         this.data.set(id, { ...record });
         this.addToIndexes(id, record);
+        return Promise.resolve();
     }
-    async put(record) {
+    put(record) {
         const id = record.id;
         if (!id)
-            return;
+            return Promise.resolve();
         // Remove from old index entries if updating
         const existing = this.data.get(id);
         if (existing) {
@@ -45,24 +46,26 @@ export class InMemoryObjectStore {
         }
         this.data.set(id, { ...record });
         this.addToIndexes(id, record);
+        return Promise.resolve();
     }
-    async get(id) {
-        return this.data.get(id);
+    get(id) {
+        return Promise.resolve(this.data.get(id));
     }
-    async getAll() {
-        return [...this.data.values()];
+    getAll() {
+        return Promise.resolve([...this.data.values()]);
     }
-    async delete(id) {
+    delete(id) {
         const existing = this.data.get(id);
         if (existing) {
             this.removeFromIndexes(id, existing);
             this.data.delete(id);
         }
+        return Promise.resolve();
     }
-    async getAllFromIndex(indexName, value) {
+    getAllFromIndex(indexName, value) {
         const index = this.indexes.get(indexName);
         if (!index)
-            return [];
+            return Promise.resolve([]);
         // The in-memory index stores values as strings (it doesn't support
         // the full IDB key range — Date / BufferSource / arrays). For the
         // overwhelmingly-common case of string FK ids, coercing through
@@ -70,16 +73,17 @@ export class InMemoryObjectStore {
         // shared `ObjectStoreContract` signature.
         const ids = index.get(String(value));
         if (!ids)
-            return [];
-        return [...ids]
+            return Promise.resolve([]);
+        return Promise.resolve([...ids]
             .map((id) => this.data.get(id))
-            .filter((r) => r != null);
+            .filter((r) => r != null));
     }
-    async clear() {
+    clear() {
         this.data.clear();
         for (const index of this.indexes.values()) {
             index.clear();
         }
+        return Promise.resolve();
     }
     /** No-op — in-memory stores don't need closing. */
     markAsClosing() { }

package/dist/ai-sdk/coordinatedTool.d.ts

@@ -58,7 +58,9 @@
  *   first-in-first-out, which would require a persistent connection.
  */
 import type { z } from 'zod';
-import type { ModelOperations } from '../client/createModelProxy.js';
+import type { ClaimParams, ModelRetrieveParams, ModelUpdateParams } from '../client/createModelProxy.js';
+import type { ModelUpdater, ContentionOptions } from '../client/functionalUpdate.js';
+import type { HeldClaim } from '../types/streams.js';
 export type CoordinationStrategy = 'merge' | 'claim' | 'queue';
 /** The structured result the tool hands back to the model (or the caller). */
 export interface CoordinatedWriteResult<T> {
@@ -105,4 +107,15 @@ export interface CoordinatedToolOptions<TInput, T> {
         timeoutMs?: number;
     };
 }
-export declare function coordinatedTool<TInput, T = Record<string, unknown>, CreateInput = Partial<T>>(model: ModelOperations<T, CreateInput>, options: CoordinatedToolOptions<TInput, T>): import("ai").Tool<TInput, CoordinatedWriteResult<T>>;
+/**
+ * The small model port this helper needs. Both typed transports implement this
+ * exact contract; local-cache methods, wire receipts, and transport lifecycle
+ * deliberately stay out of an AI tool's dependency surface.
+ */
+export interface CoordinatedModel<T> {
+    retrieve(params: ModelRetrieveParams): Promise<T | undefined>;
+    update(params: ModelUpdateParams<T>): Promise<T>;
+    update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<T | undefined>;
+    claim(params: ClaimParams<T>): Promise<HeldClaim<T>>;
+}
+export declare function coordinatedTool<TInput, T = Record<string, unknown>>(model: CoordinatedModel<T>, options: CoordinatedToolOptions<TInput, T>): import("ai").Tool<TInput, CoordinatedWriteResult<T>>;

package/dist/auth/schemas.d.ts

@@ -27,6 +27,12 @@ export declare const IdentityResolveResponseSchema: z.ZodObject<{
     }>;
     participantId: z.ZodString;
     accountScope: z.ZodString;
+    projectId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    environment: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>>>;
+    sandboxId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     syncGroups: z.ZodArray<z.ZodString>;
     userMeta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$loose>;

package/dist/auth/schemas.js

@@ -25,6 +25,13 @@ export const IdentityResolveResponseSchema = z
     participantKind: AuthParticipantKindSchema,
     participantId: z.string().min(1),
     accountScope: z.string().min(1),
+    // The rest of the plane this credential resolves to. `nullish` (optional +
+    // nullable) so a server too old to send them still parses, and a human
+    // session — which carries no such scope — validates with them absent.
+    // `projectId` equals the org id for the org-default project.
+    projectId: z.string().min(1).nullish(),
+    environment: z.enum(['sandbox', 'production']).nullish(),
+    sandboxId: z.string().min(1).nullish(),
     syncGroups: z.array(z.string()),
     userMeta: z.record(z.string(), z.unknown()),
 })