@abloatai/ablo 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 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/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 ?? []),
         ],
     });