@abloatai/ablo 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.20.0
+
+### Minor Changes
+
+- Reactive reads now work out of the box. A read like `useAblo((a) => a.documents.get(id))` re-renders when a live delta updates the row — including in-place field updates (the common collaborative case), which previously fired no reaction and left the UI silently stale.
+
+  Two changes make this work:
+  - **Models are reactive by default.** Schema fields are now MobX-observable without opting in. `json` fields stay `observable.ref` (one atom for the whole blob, not a deep atom tree per node), so the default is cheap. Opt out per model with `lazyObservable: false` for very large read-only list models where the QueryView's entry-replaced reactivity is enough.
+  - **`useAblo` returns a plain row snapshot** (via the new `Model.toReactiveSnapshot()`) instead of the live model instance. Reading the fields inside the tracked function is what subscribes the reaction (MobX tracks property access, not values), and the fresh snapshot identity lets the hook detect the change. Consumers get plain row objects and never touch a MobX observable directly.
+
+  Also new: `deepEqual` and `stableStringify` exports for comparing `field.json()` values. A `jsonb`-backed json field round-trips with reordered object keys (Postgres `jsonb` does not preserve key order), so a naive `JSON.stringify(a) === JSON.stringify(b)` comparison is unreliable when reconciling against external state (e.g. a rich-text editor). These helpers compare key-order-insensitively.
+
+## 0.19.0
+
+### Minor Changes
+
+- **Claim observability — a `ClaimLog` you can print or assert on.** A new
+  `observability` provider hook lets you tap every claim event and stale-write
+  collision the client sees. Hand `new ClaimLog()` to `Ablo({ observability })`
+  and it collects an ordered, readable log — `formatClaim` / `formatConflict`
+  render one line per event, and `collisions()` returns the conflicts for eval
+  assertions. New exports: `ClaimLog`, `formatClaim`, `formatConflict`,
+  `noopObservability`, and the types `ClaimLogEntry`, `ClaimEvent`,
+  `ConflictEvent`, `SyncObservabilityProvider`. Spread `noopObservability` to
+  override only the hooks you care about.
+
+  **AWS-shaped CLI credential store + `ablo config`.** Local CLI state is now split
+  into two files, matching `~/.aws/config` vs `~/.aws/credentials`: `config.json`
+  holds non-secret settings (active environment + active project) and is safe to
+  print or let an agent read; `credentials.json` holds the keys (0600, never
+  printed), keyed by project profile then environment. Per-project profiles follow
+  Stripe's model — `ablo projects use <slug>` selects the active profile, and a
+  key's project is fixed at mint so selecting a project never re-scopes an existing
+  key. `ablo status` now reports the resolved profile and environment.
+
+  **Schema JSON-column reconciliation.** `generateJsonColumnReconciliation` (new
+  export) emits the DDL to reconcile JSON-backed columns when adopting or evolving
+  an existing schema.
+
+  **Breaking (0.x):**
+  - The claim handle type `ClaimHandle` is renamed to **`Claim`**, and its
+    identifier field is `id` (was `claimId`). Update type imports and any code
+    reading `.claimId`.
+  - The ai-sdk `claimBroadcastMiddleware` (and `./ai-sdk/claim-broadcast`) is
+    removed — coordination broadcast is handled by `coordinationContextMiddleware`.
+    Import `ClaimTarget` from the package root or `@abloatai/ablo` ai-sdk's
+    `coordination-context` instead of `claim-broadcast`. The inline-claim option is
+    `reason` (not the pre-0.12 `action`); the ai-sdk docs are corrected to match.
+
 ## 0.18.0
 
 ### Minor Changes

package/dist/Model.d.ts

@@ -359,6 +359,28 @@ export declare abstract class Model {
      * Capture snapshot for change detection
      */
     protected captureSnapshot(): ModelData;
+    /**
+     * A fresh, plain row snapshot that READS every declared field through its
+     * MobX observable getter. This is the reactive read surface for
+     * `useReactive`/`useAblo`, and it relies on two MobX facts:
+     *
+     *  1. MobX tracks property *access*, not values — so reading each field here,
+     *     inside the caller's tracked function, SUBSCRIBES the reaction to that
+     *     field. A bare `return model` (the previous `modelAsRow`) dereferences
+     *     nothing, so an in-place delta update fires no reaction and the UI never
+     *     re-renders. (https://mobx.js.org/understanding-reactivity.html)
+     *  2. The returned object is a NEW identity each call, so the hook's equality
+     *     check detects the change — the same mutated instance would compare equal
+     *     and suppress the re-render even after tracking fired.
+     *
+     * Unlike `toJSON()`, values keep their runtime types (a `Date` stays a `Date`,
+     * a json field stays its parsed object) and wire-noise keys
+     * (`__class`/`clientId`/`syncStatus`) are omitted — this is exactly the row
+     * the schema's `T` describes. Computed relations (`referenceModel`/
+     * `referenceCollection`) and ephemeral fields are skipped, matching `toJSON`'s
+     * row projection; they're lazy/recursive and not part of the row's data.
+     */
+    toReactiveSnapshot<T = ModelData>(): T;
     /**
      * Get field changes for activity tracking
      */

package/dist/Model.js

@@ -731,6 +731,51 @@ export class Model {
         }
         return snapshot;
     }
+    /**
+     * A fresh, plain row snapshot that READS every declared field through its
+     * MobX observable getter. This is the reactive read surface for
+     * `useReactive`/`useAblo`, and it relies on two MobX facts:
+     *
+     *  1. MobX tracks property *access*, not values — so reading each field here,
+     *     inside the caller's tracked function, SUBSCRIBES the reaction to that
+     *     field. A bare `return model` (the previous `modelAsRow`) dereferences
+     *     nothing, so an in-place delta update fires no reaction and the UI never
+     *     re-renders. (https://mobx.js.org/understanding-reactivity.html)
+     *  2. The returned object is a NEW identity each call, so the hook's equality
+     *     check detects the change — the same mutated instance would compare equal
+     *     and suppress the re-render even after tracking fired.
+     *
+     * Unlike `toJSON()`, values keep their runtime types (a `Date` stays a `Date`,
+     * a json field stays its parsed object) and wire-noise keys
+     * (`__class`/`clientId`/`syncStatus`) are omitted — this is exactly the row
+     * the schema's `T` describes. Computed relations (`referenceModel`/
+     * `referenceCollection`) and ephemeral fields are skipped, matching `toJSON`'s
+     * row projection; they're lazy/recursive and not part of the row's data.
+     */
+    toReactiveSnapshot() {
+        const snapshot = {
+            id: this.id,
+            createdAt: this.createdAt,
+            updatedAt: this.updatedAt,
+        };
+        if (this.archivedAt !== undefined)
+            snapshot.archivedAt = this.archivedAt;
+        const properties = getActiveRegistry().getProperties(this.getModelName());
+        if (properties) {
+            const self = this;
+            for (const [propName, metadata] of properties) {
+                if (metadata.type === 'ephemeralProperty' ||
+                    metadata.type === 'referenceModel' ||
+                    metadata.type === 'referenceCollection') {
+                    continue;
+                }
+                // Reading through the observable getter is the point: it subscribes the
+                // enclosing MobX reaction to this field.
+                snapshot[propName] = self[propName];
+            }
+        }
+        return snapshot;
+    }
     /**
      * Get field changes for activity tracking
      */

package/dist/ObjectPool.d.ts

@@ -111,7 +111,20 @@ export declare class ObjectPool {
         __class?: string;
         modelName?: string;
         id?: string;
-    }, ModelClass?: new (data: Record<string, unknown>) => Model): Model | null;
+    }, ModelClass?: new (data: Record<string, unknown>) => Model, opts?: {
+        /**
+         * Throw (instead of warn + return null) when the wire names a model
+         * this client never registered. Passed by the developer-await read
+         * path (`HydrationCoordinator`'s network leg) so a schema collision
+         * — the org's pushed schema names `Document` but this client only
+         * registered `documents` — surfaces AT the row that failed, with the
+         * known-model list and `ablo status` pointer, instead of bubbling up
+         * three layers later as a misleading `entity_not_found`. Left off
+         * (default) for the continuous delta loop and IDB-cache hydration,
+         * where a single unknown typename must not wedge the whole batch.
+         */
+        strict?: boolean;
+    }): Model | null;
     /**
      * Clear the object pool
      * @param options.preserveObserved - If true, keep models that are being observed by React

package/dist/ObjectPool.js

@@ -603,7 +603,7 @@ export class ObjectPool {
     create(typename, data) {
         return this.createFromData({ ...data, __typename: typename });
     }
-    createFromData(data, ModelClass) {
+    createFromData(data, ModelClass, opts) {
         // Support multiple model identifier fields for backwards compatibility
         const modelName = data.__typename ?? data.__class ?? data.modelName ?? 'Unknown';
         const Constructor = ModelClass || this.registry.getModelByName(modelName);
@@ -613,6 +613,13 @@ export class ObjectPool {
                 getContext().modelDebugLogger?.logError('Unknown', 'CREATE', 'No model identifier found', data);
                 return null;
             }
+            if (opts?.strict) {
+                const known = this.registry.getRegisteredModelNames();
+                throw new AbloValidationError(`Model "${modelName}" is not registered on this client` +
+                    (known.length ? ` (known: ${known.join(', ')})` : '') +
+                    `. The schema pushed to this org may differ from your local ` +
+                    `schema — run \`ablo status\` to compare.`, { code: 'model_not_registered' });
+            }
             getContext().logger.warn(`ObjectPool.createFromData: No constructor found for model "${modelName}"`, { data });
             getContext().modelDebugLogger?.logError(modelName, 'CREATE', `No constructor found for model "${modelName}"`, data);
             return null;

package/dist/SyncClient.js

@@ -161,8 +161,14 @@ export class SyncClient extends EventEmitter {
             // (e.g. `AbloValidationError` with `code: 'schema_...'`,
             // `AbloServerError` with `httpStatus: 500`). Falling back to
             // generic message lets us still see unstructured errors.
+            // Mechanic-level breadcrumb only. The authoritative, user-facing
+            // reason is logged once at `warn` by `TransactionQueue.handleFailure`
+            // (`Permanent error - rolling back`). Logging the same typed cause
+            // again here at `warn` is what produced three identical dumps per
+            // rejected write — keep it at `debug` so the rollback mechanics are
+            // available when debugging but don't double the console noise.
             const abloErr = error instanceof AbloError ? error : undefined;
-            getContext().logger.warn('[SyncClient.rollback]', {
+            getContext().logger.debug('[SyncClient.rollback]', {
                 txType: transaction.type,
                 modelName: transaction.modelName,
                 modelId: transaction.modelId.slice(0, 12),

package/dist/SyncEngineContext.js

@@ -28,6 +28,8 @@ export const noopObservability = {
     captureWebSocketError() { },
     captureOfflineFlushFailure() { },
     captureSelfHealing() { },
+    captureClaim() { },
+    captureConflict() { },
     captureCommitZeroSyncId() { },
     startSpan(_name, _op, fn, _attributes) {
         return fn();

package/dist/ai-sdk/coordination-context.d.ts

@@ -23,7 +23,8 @@
 import type { LanguageModelV3Middleware } from '@ai-sdk/provider';
 import type { Ablo } from '../client/Ablo.js';
 import type { SchemaRecord } from '../schema/schema.js';
-import type { ClaimTarget } from './claim-broadcast.js';
+import type { ClaimTarget } from '../types/streams.js';
+export type { ClaimTarget };
 export interface CoordinationContextMiddlewareOptions<R extends SchemaRecord = SchemaRecord> {
     readonly agent: Ablo<R> | null;
     readonly target: ClaimTarget | null;

package/dist/ai-sdk/coordination-context.js

@@ -38,8 +38,8 @@ export function coordinationContextMiddleware(options) {
                 return params;
             // Read peer claims on the same target. Synchronous lookup
             // against the engine's reactive claims.others array — no I/O.
-            const peerClaims = agent.claims.others.filter((claim) => claim.target.type === target.entityType &&
-                claim.target.id === target.entityId &&
+            const peerClaims = agent.claims.others.filter((claim) => claim.target.type === target.type &&
+                claim.target.id === target.id &&
                 targetsOverlap(claim.target, target) &&
                 !excludeClaimIds.has(claim.id));
             if (peerClaims.length === 0)
@@ -77,7 +77,7 @@ function targetsOverlap(claimTarget, target) {
  * "AI knows," not "AI gets a wall of text."
  */
 function formatCoordinationNote(claims, target) {
-    const entityLabel = target.entityType.toLowerCase();
+    const entityLabel = target.type.toLowerCase();
     if (claims.length === 1) {
         const c = claims[0];
         const details = c.description ? `Declared work: ${c.description}. ` : '';

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

@@ -27,7 +27,7 @@
  *       wait: 'confirmed',
  *       claim: {
  *         field: 'title',
- *         action: 'renaming',
+ *         reason: 'renaming',
  *         description,
  *       },
  *     });
@@ -51,7 +51,7 @@
  * ```ts
  * const claim = await ablo.tasks.claim({
  *   id,
- *   action: 'rewriting',
+ *   reason: 'rewriting',
  *   description: 'Rewriting the task brief before updating follow-up fields.',
  *   ttl: '2m',
  * });
@@ -72,6 +72,5 @@
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
  */
-export { claimBroadcastMiddleware, type ClaimTarget, type ClaimBroadcastMiddlewareOptions, } from './claim-broadcast.js';
-export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, } from './coordination-context.js';
+export { coordinationContextMiddleware, type CoordinationContextMiddlewareOptions, type ClaimTarget, } from './coordination-context.js';
 export { wrapWithMultiplayer, type WrapWithMultiplayerOptions } from './wrap.js';

package/dist/ai-sdk/index.js

@@ -27,7 +27,7 @@
  *       wait: 'confirmed',
  *       claim: {
  *         field: 'title',
- *         action: 'renaming',
+ *         reason: 'renaming',
  *         description,
  *       },
  *     });
@@ -51,7 +51,7 @@
  * ```ts
  * const claim = await ablo.tasks.claim({
  *   id,
- *   action: 'rewriting',
+ *   reason: 'rewriting',
  *   description: 'Rewriting the task brief before updating follow-up fields.',
  *   ttl: '2m',
  * });
@@ -72,6 +72,5 @@
  * to one entity before any tool is chosen; tool implementations stay exactly
  * the same.
  */
-export { claimBroadcastMiddleware, } from './claim-broadcast.js';
 export { coordinationContextMiddleware, } from './coordination-context.js';
 export { wrapWithMultiplayer } from './wrap.js';

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

@@ -14,8 +14,6 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   reason: 'renaming',
- *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
  * const result = streamText({
@@ -31,25 +29,22 @@ import { wrapLanguageModel } from 'ai';
 import type { LanguageModelV3, LanguageModelV3Middleware } from '@ai-sdk/provider';
 import type { Ablo } from '../client/Ablo.js';
 import type { SchemaRecord } from '../schema/schema.js';
-import { type ClaimTarget } from './claim-broadcast.js';
-export interface WrapWithMultiplayerOptions {
+import { type ClaimTarget } from './coordination-context.js';
+export interface WrapWithMultiplayerOptions<R extends SchemaRecord = SchemaRecord> {
     /** The base language model to wrap. Consumer brings their own. */
     readonly model: LanguageModelV3;
-    /** Connected SyncAgent. Null = pass-through wrap (no broadcast, no read). */
-    readonly agent: Ablo<SchemaRecord> | null;
-    /** Target entity. Null = pass-through wrap. */
-    readonly target: ClaimTarget | null;
-    /**
-     * Optional human-readable phase for the broadcast. Default `'edit'`.
-     * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`. The same
-     * `reason` field used on every claim surface.
-     */
-    readonly reason?: string;
     /**
-     * Peer-visible explanation of the specific work this model call is about to
-     * perform. Other agents receive it in their coordination context.
+     * Connected Ablo. Null = pass-through wrap (no broadcast, no read).
+     *
+     * Generic over the schema record (like the two middlewares it composes) so a
+     * caller passing a typed `Ablo<typeof schema>` doesn't have to cast: `Ablo<S>`
+     * and `Ablo<SchemaRecord>` aren't structurally assignable (the widened version
+     * collapses model proxies to an index signature that clashes with the named
+     * methods `ready`/`dispose`/…).
      */
-    readonly description?: string;
+    readonly agent: Ablo<R> | null;
+    /** Target entity. Null = pass-through wrap. */
+    readonly target: ClaimTarget | null;
     /**
      * Optional claimIds to exclude from the coordination-context
      * read — typically the caller's own claim if they're composing
@@ -68,4 +63,4 @@ export interface WrapWithMultiplayerOptions {
      */
     readonly extraMiddleware?: readonly LanguageModelV3Middleware[];
 }
-export declare function wrapWithMultiplayer(options: WrapWithMultiplayerOptions): ReturnType<typeof wrapLanguageModel>;
+export declare function wrapWithMultiplayer<R extends SchemaRecord = SchemaRecord>(options: WrapWithMultiplayerOptions<R>): ReturnType<typeof wrapLanguageModel>;

package/dist/ai-sdk/wrap.js

@@ -14,8 +14,6 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   reason: 'renaming',
- *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
  * const result = streamText({
@@ -28,15 +26,13 @@
  * ```
  */
 import { wrapLanguageModel } from 'ai';
-import { claimBroadcastMiddleware, } from './claim-broadcast.js';
-import { coordinationContextMiddleware } from './coordination-context.js';
+import { coordinationContextMiddleware, } from './coordination-context.js';
 export function wrapWithMultiplayer(options) {
-    const { model, agent, target, reason, description, excludeClaimIds, extraMiddleware } = options;
+    const { model, agent, target, excludeClaimIds, extraMiddleware } = options;
     return wrapLanguageModel({
         model,
         middleware: [
             coordinationContextMiddleware({ agent, target, excludeClaimIds }),
-            claimBroadcastMiddleware({ agent, target, reason, description }),
             ...(extraMiddleware ?? []),
         ],
     });