@abloatai/ablo 0.17.0 → 0.19.0

package/dist/client/sessionMint.js

@@ -63,7 +63,14 @@ export async function mintSession(params, ctx) {
             userMeta: params.userMeta ?? { id: res.participantId },
         };
     }
-    const operations = Object.entries(params.can).flatMap(([model, ops]) => (ops ?? []).map((op) => `${model.toLowerCase()}.${op}`));
+    const operations = Object.entries(params.can).flatMap(([model, ops]) => {
+        // Translate the schema key the developer used in `can` to the wire
+        // typename the Hub gates on — see `modelTypenames` above. Falls back to
+        // the key when no map is supplied (schemaless client) or the key isn't
+        // in it, preserving the prior behaviour exactly for those callers.
+        const ns = ctx.modelTypenames?.[model] ?? model;
+        return (ops ?? []).map((op) => `${ns.toLowerCase()}.${op}`);
+    });
     const res = await exchangeApiKey({
         apiKey,
         baseUrl,

package/dist/coordination/schema.d.ts

@@ -209,7 +209,7 @@ export declare const wireClaimSummarySchema: z.ZodObject<{
     entityId: z.ZodString;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     claimId: z.ZodString;
-    action: z.ZodString;
+    reason: z.ZodString;
     declaredAt: z.ZodNumber;
     expiresAt: z.ZodNumber;
 }, z.core.$strip>;
@@ -227,7 +227,7 @@ export declare const claimErrorSchema: z.ZodObject<{
         entityId: z.ZodString;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         claimId: z.ZodString;
-        action: z.ZodString;
+        reason: z.ZodString;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
     }, z.core.$strip>>;
@@ -237,7 +237,7 @@ export type ClaimError = z.infer<typeof claimErrorSchema>;
 /**
  * A declared pending-mutation claim — the unit broadcast in presence
  * `activeClaims`. Clients supply the descriptive `targetRef` fields, an
- * `action`, and a chosen `claimId`; the SERVER stamps `declaredAt` /
+ * explanatory `reason`, and a chosen `claimId`; the SERVER stamps `declaredAt` /
  * `expiresAt` and may set `status` / `error`.
  *
  * `status` and `error` are OPTIONAL: this single shape serves both the
@@ -259,7 +259,7 @@ export declare const wireClaimSchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     claimId: z.ZodString;
-    action: z.ZodString;
+    reason: z.ZodString;
     declaredAt: z.ZodNumber;
     expiresAt: z.ZodNumber;
     status: z.ZodOptional<z.ZodEnum<{
@@ -280,7 +280,7 @@ export declare const wireClaimSchema: z.ZodObject<{
             entityId: z.ZodString;
             meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             claimId: z.ZodString;
-            action: z.ZodString;
+            reason: z.ZodString;
             declaredAt: z.ZodNumber;
             expiresAt: z.ZodNumber;
         }, z.core.$strip>>;
@@ -313,7 +313,7 @@ export declare const claimRejectionSchema: z.ZodObject<{
         entityId: z.ZodString;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         claimId: z.ZodString;
-        action: z.ZodString;
+        reason: z.ZodString;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
     }, z.core.$strip>>;
@@ -385,7 +385,7 @@ export declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
 }, z.core.$strip>>;
 export type ModelClaim = z.infer<typeof modelClaimSchema>;
 /**
- * `claim_begin` payload (client → server). The descriptive target + action,
+ * `claim_begin` payload (client → server). The descriptive target + reason,
  * plus an optional duration hint and the opt-in fair-queue flag. The server
  * stamps the lifecycle/timestamp fields, so they are NOT part of the inbound
  * shape — this is exactly what the WS ingest validates.
@@ -403,7 +403,7 @@ export declare const claimBeginPayloadSchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     claimId: z.ZodString;
-    action: z.ZodString;
+    reason: z.ZodString;
     estimatedMs: z.ZodOptional<z.ZodNumber>;
     queue: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
@@ -585,7 +585,7 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
         field: z.ZodOptional<z.ZodString>;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         claimId: z.ZodString;
-        action: z.ZodString;
+        reason: z.ZodString;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
         status: z.ZodOptional<z.ZodEnum<{
@@ -606,7 +606,7 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
                 entityId: z.ZodString;
                 meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 claimId: z.ZodString;
-                action: z.ZodString;
+                reason: z.ZodString;
                 declaredAt: z.ZodNumber;
                 expiresAt: z.ZodNumber;
             }, z.core.$strip>>;

package/dist/coordination/schema.js

@@ -209,8 +209,8 @@ export const claimStatusSchema = z.enum([
 ]);
 const wireClaimBaseSchema = targetRefSchema.extend({
     claimId: z.string(),
-    /** Verb the agent expects: 'update' | 'create' | 'editing' | 'reviewing' … */
-    action: z.string(),
+    /** Human-readable phase: 'editing' | 'reviewing' | 'forecasting' … */
+    reason: z.string(),
     /** Server-stamped declaration time (epoch ms). */
     declaredAt: z.number(),
     /** Server-computed TTL deadline (epoch ms). Readers treat as advisory. */
@@ -219,7 +219,7 @@ const wireClaimBaseSchema = targetRefSchema.extend({
 });
 export const wireClaimSummarySchema = wireClaimBaseSchema.pick({
     claimId: true,
-    action: true,
+    reason: true,
     declaredAt: true,
     expiresAt: true,
     entityType: true,
@@ -243,7 +243,7 @@ export const claimErrorSchema = z.object({
 /**
  * A declared pending-mutation claim — the unit broadcast in presence
  * `activeClaims`. Clients supply the descriptive `targetRef` fields, an
- * `action`, and a chosen `claimId`; the SERVER stamps `declaredAt` /
+ * explanatory `reason`, and a chosen `claimId`; the SERVER stamps `declaredAt` /
  * `expiresAt` and may set `status` / `error`.
  *
  * `status` and `error` are OPTIONAL: this single shape serves both the
@@ -298,8 +298,7 @@ export const modelClaimSchema = z
     id: z.string(),
     actor: z.string(),
     participantKind: wireParticipantKindSchema,
-    /** Human-readable phase (`'editing'`). The public SDK field; the WS/HTTP
-     *  wire carries the same value as `action` (healed on read). */
+    /** Human-readable phase (`'editing'`). */
     reason: z.string(),
     description: z.string().optional(),
     field: z.string().optional(),
@@ -310,14 +309,14 @@ export const modelClaimSchema = z
 })
     .readonly();
 /**
- * `claim_begin` payload (client → server). The descriptive target + action,
+ * `claim_begin` payload (client → server). The descriptive target + reason,
  * plus an optional duration hint and the opt-in fair-queue flag. The server
  * stamps the lifecycle/timestamp fields, so they are NOT part of the inbound
  * shape — this is exactly what the WS ingest validates.
  */
 export const claimBeginPayloadSchema = targetRefSchema.extend({
     claimId: z.string(),
-    action: z.string(),
+    reason: z.string(),
     /** Hint for `expiresAt`; the server caps it. */
     estimatedMs: z.number().optional(),
     /**

package/dist/coordination/trace.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Claim log — the easy way to SEE agents colliding.
+ *
+ * The engine emits the claim lifecycle (`acquired → queued → granted → lost /
+ * rejected / expired`) and the notify-instead-of-abort stale-write collision
+ * through two seams: human `logger` lines (visible with `new Ablo({ debug: true })`)
+ * and structured `observability.captureClaim` / `captureConflict` calls.
+ *
+ * This is the third, evals-shaped path: hand a {@link ClaimLog} to
+ * `Ablo({ observability })`, run your scenario, then read back an ordered list
+ * you can print for eyeballing or `collisions()` for assertions.
+ */
+import type { SyncObservabilityProvider, ClaimEvent, ConflictEvent } from '../interfaces/index.js';
+/** A claim state change as one quiet, greppable line. */
+export declare function formatClaim(e: ClaimEvent): string;
+/** A notify-instead-of-abort stale write as one readable line. */
+export declare function formatConflict(e: ConflictEvent): string;
+/** One ordered entry in a {@link ClaimLog}. */
+export interface ClaimLogEntry {
+    /** Monotonic order index — deterministic, clock-free, eval-friendly. */
+    readonly seq: number;
+    /** The same one-line text the console and breadcrumb seams emit. */
+    readonly line: string;
+    /** A collision worth flagging: a rejected/lost claim or a stale write. */
+    readonly collision: boolean;
+    readonly claim?: ClaimEvent;
+    readonly conflict?: ConflictEvent;
+}
+/**
+ * Collects the claim lifecycle + stale-write collisions into an ordered list.
+ *
+ * @example
+ * ```ts
+ * const log = new ClaimLog();
+ * const ablo = new Ablo({ schema, apiKey, observability: log });
+ * // …run the agents…
+ * console.log(`${log}`);                 // pretty timeline for eyeballing
+ * expect(log.collisions()).toHaveLength(0); // assert no one stepped on anyone
+ * ```
+ *
+ * Implements the full {@link SyncObservabilityProvider} (every method it does not
+ * care about is an inert no-op), so it drops straight into the `observability`
+ * slot with no adapter.
+ */
+export declare class ClaimLog implements SyncObservabilityProvider {
+    private readonly max;
+    private rows;
+    private seq;
+    private readonly listeners;
+    /** Cap the buffer so a long-running session can't grow unbounded. */
+    constructor(max?: number);
+    captureClaim(claim: ClaimEvent): void;
+    captureConflict(conflict: ConflictEvent): void;
+    /**
+     * Fire `listener` every time an event lands. Returns an unsubscribe fn. Same
+     * contract as `ablo.claims.onChange` — drop it into `useSyncExternalStore` in
+     * React or `autorun` in MobX to render a live activity feed.
+     *
+     * @example
+     * ```tsx
+     * const log = useMemo(() => new ClaimLog(), []);
+     * const entries = useSyncExternalStore(log.onChange, () => log.entries);
+     * return <ul>{entries.map((e) => <li key={e.seq}>{e.line}</li>)}</ul>;
+     * ```
+     */
+    readonly onChange: (listener: () => void) => (() => void);
+    /** The full ordered list. Stable reference until the next event lands. */
+    get entries(): readonly ClaimLogEntry[];
+    /** Only the collisions: rejected/lost claims + stale writes. */
+    collisions(): readonly ClaimLogEntry[];
+    /** Drop everything — useful between scenarios in one process. */
+    clear(): void;
+    /** Printable: one event per line, collisions marked. */
+    toString(): string;
+    private add;
+    private notify;
+    setContext(): void;
+    setConnectionState(): void;
+    breadcrumb(): void;
+    captureRollback(): void;
+    captureTransactionFailure(): void;
+    captureBootstrapFailure(): void;
+    captureReconciliation(): void;
+    captureDeltaRetryExhausted(): void;
+    captureWebSocketError(): void;
+    captureOfflineFlushFailure(): void;
+    captureSelfHealing(): void;
+    captureCommitZeroSyncId(): void;
+    startSpan<T>(_name: string, _op: string, fn: () => T): T;
+    startSpanAsync<T>(_name: string, _op: string, fn: () => Promise<T>): Promise<T>;
+}

package/dist/coordination/trace.js

@@ -0,0 +1,147 @@
+/**
+ * Claim log — the easy way to SEE agents colliding.
+ *
+ * The engine emits the claim lifecycle (`acquired → queued → granted → lost /
+ * rejected / expired`) and the notify-instead-of-abort stale-write collision
+ * through two seams: human `logger` lines (visible with `new Ablo({ debug: true })`)
+ * and structured `observability.captureClaim` / `captureConflict` calls.
+ *
+ * This is the third, evals-shaped path: hand a {@link ClaimLog} to
+ * `Ablo({ observability })`, run your scenario, then read back an ordered list
+ * you can print for eyeballing or `collisions()` for assertions.
+ */
+// ─────────────────────────────────────────────
+// Formatters — one readable line per event. Shared by the WS logger seam and
+// the log so console output and log output never drift.
+// ─────────────────────────────────────────────
+/** A claim state change as one quiet, greppable line. */
+export function formatClaim(e) {
+    const target = e.model && e.id ? `${e.model}/${e.id}` : e.claimId ?? 'unknown target';
+    const scope = e.field ? `#${e.field}` : '';
+    const pos = e.position !== undefined ? ` [pos ${e.position}]` : '';
+    const actor = e.actor
+        ? `${e.actor}${e.participantKind ? ` (${e.participantKind})` : ''}`
+        : '';
+    // `rejected`/`lost` name the BLOCKING holder; the rest name us (or no one).
+    const by = actor
+        ? e.phase === 'rejected' || e.phase === 'lost'
+            ? ` — held by ${actor}`
+            : ` — by ${actor}`
+        : '';
+    const why = e.reason ? `: ${e.reason}` : '';
+    return `claim ${e.phase}: ${target}${scope}${pos}${by}${why}`;
+}
+/** A notify-instead-of-abort stale write as one readable line. */
+export function formatConflict(e) {
+    const rows = e.rows.map((r) => `${r.model}/${r.id}(${r.fields.join(',')})`).join(', ');
+    return `conflict: tx ${e.clientTxId} — ${e.rows.length} row(s) changed underneath${rows ? `: ${rows}` : ''}`;
+}
+/**
+ * Collects the claim lifecycle + stale-write collisions into an ordered list.
+ *
+ * @example
+ * ```ts
+ * const log = new ClaimLog();
+ * const ablo = new Ablo({ schema, apiKey, observability: log });
+ * // …run the agents…
+ * console.log(`${log}`);                 // pretty timeline for eyeballing
+ * expect(log.collisions()).toHaveLength(0); // assert no one stepped on anyone
+ * ```
+ *
+ * Implements the full {@link SyncObservabilityProvider} (every method it does not
+ * care about is an inert no-op), so it drops straight into the `observability`
+ * slot with no adapter.
+ */
+export class ClaimLog {
+    max;
+    // Immutable list: a NEW array reference on every change. This is what lets
+    // `useSyncExternalStore(log.onChange, () => log.entries)` detect updates —
+    // it compares snapshots by reference, so an in-place push would never render.
+    rows = [];
+    seq = 0;
+    listeners = new Set();
+    /** Cap the buffer so a long-running session can't grow unbounded. */
+    constructor(max = 1_000) {
+        this.max = max;
+    }
+    // —— the two seams we record ——
+    captureClaim(claim) {
+        this.add({
+            line: formatClaim(claim),
+            collision: claim.phase === 'rejected' || claim.phase === 'lost',
+            claim,
+        });
+    }
+    captureConflict(conflict) {
+        this.add({ line: formatConflict(conflict), collision: true, conflict });
+    }
+    // —— reactivity ——
+    /**
+     * Fire `listener` every time an event lands. Returns an unsubscribe fn. Same
+     * contract as `ablo.claims.onChange` — drop it into `useSyncExternalStore` in
+     * React or `autorun` in MobX to render a live activity feed.
+     *
+     * @example
+     * ```tsx
+     * const log = useMemo(() => new ClaimLog(), []);
+     * const entries = useSyncExternalStore(log.onChange, () => log.entries);
+     * return <ul>{entries.map((e) => <li key={e.seq}>{e.line}</li>)}</ul>;
+     * ```
+     */
+    onChange = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    // —— inspection ——
+    /** The full ordered list. Stable reference until the next event lands. */
+    get entries() {
+        return this.rows;
+    }
+    /** Only the collisions: rejected/lost claims + stale writes. */
+    collisions() {
+        return this.rows.filter((e) => e.collision);
+    }
+    /** Drop everything — useful between scenarios in one process. */
+    clear() {
+        this.rows = [];
+        this.seq = 0;
+        this.notify();
+    }
+    /** Printable: one event per line, collisions marked. */
+    toString() {
+        if (this.rows.length === 0)
+            return 'claim log: (empty)';
+        const w = String(this.rows.length).length;
+        return this.rows
+            .map((e) => `${String(e.seq).padStart(w)}  ${e.collision ? '⚠ ' : '  '}${e.line}`)
+            .join('\n');
+    }
+    add(entry) {
+        const next = [...this.rows, { seq: this.seq++, ...entry }];
+        this.rows = next.length > this.max ? next.slice(next.length - this.max) : next;
+        this.notify();
+    }
+    notify() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    // —— inert provider surface (this log only cares about claims) ——
+    setContext() { }
+    setConnectionState() { }
+    breadcrumb() { }
+    captureRollback() { }
+    captureTransactionFailure() { }
+    captureBootstrapFailure() { }
+    captureReconciliation() { }
+    captureDeltaRetryExhausted() { }
+    captureWebSocketError() { }
+    captureOfflineFlushFailure() { }
+    captureSelfHealing() { }
+    captureCommitZeroSyncId() { }
+    startSpan(_name, _op, fn) {
+        return fn();
+    }
+    startSpanAsync(_name, _op, fn) {
+        return fn();
+    }
+}

package/dist/core/StoreManager.js

@@ -274,7 +274,9 @@ export class StoreManager {
      * Clear all stores
      */
     async clearAllStores() {
-        getContext().logger.warn('Clearing all stores');
+        // Lifecycle chatter (logout / identity switch / reset) — NOT a warning.
+        // `debug` so it's silent under the default `warn` threshold.
+        getContext().logger.debug('Clearing all stores');
         const promises = Array.from(this.stores.values()).map((store) => store.clear());
         await Promise.all(promises);
         getContext().logger.info('All stores cleared');

package/dist/errorCodes.d.ts

@@ -135,6 +135,7 @@ export declare const ERROR_CODES: {
     readonly browser_database_url_blocked: ErrorCodeSpec;
     readonly datasource_registration_failed: ErrorCodeSpec;
     readonly datasource_connection_unsupported: ErrorCodeSpec;
+    readonly datasource_direct_deprecated: ErrorCodeSpec;
     readonly capability_scope_denied: ErrorCodeSpec;
     readonly issuer_register_forbidden: ErrorCodeSpec;
     readonly capability_invalid: ErrorCodeSpec;
@@ -188,6 +189,7 @@ export declare const ERROR_CODES: {
     readonly unique_violation: ErrorCodeSpec;
     readonly check_violation: ErrorCodeSpec;
     readonly constraint_violation: ErrorCodeSpec;
+    readonly column_type_mismatch: ErrorCodeSpec;
     readonly server_execute_unknown_model: ErrorCodeSpec;
     readonly mutate_create_unknown_model: ErrorCodeSpec;
     readonly tenant_model_columns_unknown: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -125,6 +125,7 @@ export const ERROR_CODES = {
     browser_database_url_blocked: client('auth', 'A database connection string must not be used from a browser context — it carries DB credentials.'),
     datasource_registration_failed: client('auth', 'Failed to register the provided databaseUrl as a datasource.'),
     datasource_connection_unsupported: wire('validation', 400, false, 'This deployment cannot register a direct (connection string) datasource — use the signed endpoint kind.'),
+    datasource_direct_deprecated: wire('validation', 410, false, 'The direct (connection string) datasource is deprecated. Register a signed Data Source endpoint instead — your app owns the write and your credentials never leave it.'),
     // ── permission / capability (403) ──────────────────────────────────
     capability_scope_denied: wire('capability', 403, false, "The connection's resolved scope does not cover the attempted action."),
     issuer_register_forbidden: wire('permission', 403, false, 'Registering a trusted issuer requires a secret (sk_) API key.'),
@@ -201,6 +202,7 @@ export const ERROR_CODES = {
     unique_violation: wire('conflict', 409, false, 'A value violates a uniqueness constraint.'),
     check_violation: wire('validation', 400, false, 'A value violates a database check constraint.'),
     constraint_violation: wire('validation', 400, false, 'A database integrity constraint was violated.'),
+    column_type_mismatch: wire('validation', 400, false, 'A structured (JSON) value was written to a column whose database type is not jsonb. The column was not provisioned as jsonb (often a pre-existing column adopted by `ablo push`); storing the value would silently corrupt it to "[object Object]". Run `ablo migrate` to alter the column to jsonb.'),
     // ── tenant / unknown model (400) ───────────────────────────────────
     server_execute_unknown_model: wire('tenant', 400, false, 'Wrote to a model the server does not know. The server keeps its own copy of the schema — run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` before writing to new or changed models.'),
     mutate_create_unknown_model: wire('tenant', 400, false, 'Created a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` first — the server keeps its own copy of the schema.'),

package/dist/errors.d.ts

@@ -77,6 +77,15 @@ export declare class AbloError extends Error {
         request_id?: string;
         [key: string]: unknown;
     };
+    /**
+     * A single, leak-proof line for logs and `String(err)` / template
+     * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+     *
+     * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
+     * makes `console.error(richError)` an unreadable wall of text. The structured
+     * payload stays available via {@link toJSON}; this is the human one-liner.
+     */
+    toString(): string;
 }
 /**
  * Map a stable error `code` to its docs URL — the one place the convention
@@ -176,8 +185,7 @@ export interface ClaimContext {
     readonly claimId?: string;
     readonly actor?: string;
     readonly participantKind?: ParticipantKind;
-    /** Human-readable phase the holder is in (`'editing'`). Matches the public
-     *  claim surface; the wire summary carries the same value as `action`. */
+    /** Human-readable phase the holder is in (`'editing'`). */
     readonly reason?: string;
     readonly description?: string;
     readonly field?: string;

package/dist/errors.js

@@ -91,6 +91,20 @@ export class AbloError extends Error {
             ...(this.details ?? {}),
         };
     }
+    /**
+     * A single, leak-proof line for logs and `String(err)` / template
+     * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+     *
+     * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
+     * makes `console.error(richError)` an unreadable wall of text. The structured
+     * payload stays available via {@link toJSON}; this is the human one-liner.
+     */
+    toString() {
+        const code = this.code ? ` [${this.code}]` : '';
+        const docs = this.docUrl ? ` (see ${this.docUrl})` : '';
+        const req = this.requestId ? ` [request_id: ${this.requestId}]` : '';
+        return `${this.name}${code}: ${this.message}${docs}${req}`;
+    }
 }
 /**
  * Map a stable error `code` to its docs URL — the one place the convention
@@ -182,13 +196,10 @@ export class AbloStaleContextError extends AbloError {
             this.conflicts = options.conflicts;
     }
 }
-function claimAction(claim) {
+function claimReason(claim) {
     if (!claim)
         return undefined;
-    // The public `ClaimContext` exposes the phase as `reason`; the wire
-    // `WireClaimSummary` projection still carries it under `action`. Read both.
-    const c = claim;
-    return c.reason ?? c.action;
+    return claim.reason;
 }
 function claimDescription(claim) {
     if (!claim)
@@ -215,20 +226,20 @@ function secondsUntil(ms, now = Date.now()) {
 }
 export function formatClaimedErrorMessage(args) {
     const holder = claimActor(args.claim, args.heldBy);
-    const action = claimAction(args.claim);
+    const reason = claimReason(args.claim);
     const description = claimDescription(args.claim);
     const expiresIn = secondsUntil(claimExpiresAt(args.claim));
-    if (!holder && !action && !description) {
+    if (!holder && !reason && !description) {
         return args.fallback ?? `Model row is claimed: ${args.targetLabel}.`;
     }
     const actor = holder ?? 'another participant';
-    const actionPart = action ? ` (${action})` : '';
+    const reasonPart = reason ? ` (${reason})` : '';
     const descriptionPart = description ? `: ${description}` : '';
     const expiresPart = expiresIn !== undefined ? ` - expires in ${expiresIn}s` : '';
     const policyPart = args.policyReason
         ? ` Policy reason: ${args.policyReason}.`
         : '';
-    return `Claimed by ${actor}${actionPart}${descriptionPart}${expiresPart} on ${args.targetLabel}.${policyPart}`;
+    return `Claimed by ${actor}${reasonPart}${descriptionPart}${expiresPart} on ${args.targetLabel}.${policyPart}`;
 }
 /**
  * The target entity is currently claimed by another participant and the caller

package/dist/index.d.ts

@@ -52,7 +52,7 @@ export type { MutationExecutor } from './interfaces/index.js';
 export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
 export { type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
-export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './client/Ablo.js';
+export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ModelOperations, } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
@@ -62,6 +62,8 @@ export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '.
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';
+export { errorEnvelope, statusForType } from './wire/errorEnvelope.js';
+export type { ErrorEnvelope } from './wire/errorEnvelope.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
 export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
 export type { Environment, KeyPrefixEnvironment } from './environment.js';
@@ -70,6 +72,10 @@ export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';
 export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
 export type { StaleNotification, ReadDependency } from './coordination/schema.js';
+export { ClaimLog, formatClaim, formatConflict } from './coordination/trace.js';
+export type { ClaimLogEntry } from './coordination/trace.js';
+export type { ClaimEvent, ConflictEvent, SyncObservabilityProvider, } from './interfaces/index.js';
+export { noopObservability } from './SyncEngineContext.js';
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
 export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
 export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';

package/dist/index.js

@@ -85,6 +85,11 @@ export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '.
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
+// Canonical wire-egress contract (dependency-free): the error envelope shape +
+// the AbloError-subclass→HTTP-status table. Re-exported so server consumers
+// (e.g. apps/sync-server, which keeps its own self-contained copy) can assert
+// against the ONE source instead of silently drifting. See wire/errorEnvelope.ts.
+export { errorEnvelope, statusForType } from './wire/errorEnvelope.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
 export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
 // THE write-options contract — the one Zod schema for the option bag every
@@ -99,6 +104,13 @@ export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './cl
 // agent can self-heal rather than discard work (see coordination/schema.ts and
 // docs/coordination.md → "Notify, do not abort").
 export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
+// Claim log — collect claim events + stale-write collisions into an ordered list
+// you can print for eyeballing or collisions() for evals assertions. Hand
+// `new ClaimLog()` to `Ablo({ observability })`.
+export { ClaimLog, formatClaim, formatConflict } from './coordination/trace.js';
+// Spread this to provide a custom `observability` that overrides only the hooks
+// you care about (e.g. captureClaim) and no-ops the rest.
+export { noopObservability } from './SyncEngineContext.js';
 // Storage-wedge detection — lets app shells render a recovery screen when the
 // IndexedDB backing store is stuck (see core/openIDBWithTimeout.ts).
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';