@abloatai/ablo 0.17.0 → 0.19.0

package/dist/interfaces/index.d.ts

@@ -5,7 +5,7 @@
  * Consumers implement them to wire in their own logging, observability,
  * GraphQL client, session handling, and analytics.
  */
-import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
+import type { StaleNotification, ReadDependency, ParticipantKind } from '../coordination/schema.js';
 export interface SyncLogger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
@@ -15,7 +15,7 @@ export interface SyncLogger {
 /** Breadcrumb severity levels */
 export type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error';
 /** Breadcrumb categories for sync engine lifecycle events */
-export type SyncBreadcrumbCategory = 'sync.bootstrap' | 'sync.transaction' | 'sync.websocket' | 'sync.offline' | 'sync.database' | 'sync.conflict' | 'sync.groups';
+export type SyncBreadcrumbCategory = 'sync.bootstrap' | 'sync.transaction' | 'sync.websocket' | 'sync.offline' | 'sync.database' | 'sync.conflict' | 'sync.coordination' | 'sync.groups';
 export interface RollbackDetails {
     transactionType: string;
     modelName: string;
@@ -71,6 +71,45 @@ export interface CommitZeroSyncIdDetails {
 export interface OfflineFlushFailureDetails {
     error: string;
 }
+/**
+ * One thing that happened to a claim. `phase` is the past-tense state it just
+ * entered — the trail you follow to see WHY two participants collided on a row:
+ * who asked, who waited behind whom, who was turned away, whose lease lapsed.
+ * Each phase mirrors a `claim_*` wire frame.
+ */
+export interface ClaimEvent {
+    phase: 'acquired' | 'queued' | 'granted' | 'lost' | 'rejected' | 'expired';
+    /** Server claim id, when the frame carries one. */
+    claimId?: string;
+    /** The claimed row + optional field scope. */
+    model?: string;
+    id?: string;
+    field?: string;
+    /** Participant that owns or blocks the lease (on `rejected`, the holder). */
+    actor?: string;
+    participantKind?: ParticipantKind;
+    /** FIFO position when `queued`. */
+    position?: number;
+    /** Rejection or policy reason, when the server supplied one. */
+    reason?: string;
+}
+/**
+ * A committed `onStale: 'notify'` write whose premise moved — the in-flight twin
+ * of a claim collision. The commit SUCCEEDED, but the guarded ops weren't written
+ * because the row changed since the caller's `readAt`; the engine handed back the
+ * live value so the actor can self-heal. Records WHICH rows and fields collided.
+ */
+export interface ConflictEvent {
+    /** The client idempotency key whose write was notified. */
+    clientTxId: string;
+    /** The conflicted rows + the fields that collided. */
+    rows: ReadonlyArray<{
+        model: string;
+        id: string;
+        fields: readonly string[];
+        writtenBy?: ParticipantKind;
+    }>;
+}
 /** Span attributes for performance monitoring */
 export interface SpanAttributes {
     [key: string]: string | number | boolean | undefined;
@@ -102,6 +141,10 @@ export interface SyncObservabilityProvider {
     captureOfflineFlushFailure(details: OfflineFlushFailureDetails): void;
     /** Capture self-healing event */
     captureSelfHealing(details: SelfHealingDetails): void;
+    /** Capture a claim state change (acquired / queued / granted / lost / rejected / expired) */
+    captureClaim(event: ClaimEvent): void;
+    /** Capture a notify-instead-of-abort stale-write collision */
+    captureConflict(event: ConflictEvent): void;
     /** Capture commit returning lastSyncId: 0 */
     captureCommitZeroSyncId(details: CommitZeroSyncIdDetails): void;
     /** Wrap a synchronous function in a performance span */

package/dist/policy/types.d.ts

@@ -122,18 +122,40 @@ export type ConflictDecision = {
  */
 export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<ConflictDecision>;
 /**
- * Default policy.
+ * Default policy — **Law 7 (the human is the principal) is the engine-wide
+ * default, not an opt-in.**
  *
- * `claim_held` conflicts always reject (a foreign claim is honored unless a
- * privileged policy preempts). `stale_context` conflicts honor the committer's
- * declared `onStale` intent:
+ * A `claim_held` conflict resolves by the COMMITTER's kind. This default is, by
+ * construction, identical to `coordination(humansOverwrite())` applied to every
+ * model — so a developer who wants different behaviour just declares the conflict
+ * axis on that model (`humansReject()`, `humansNotify()`, `systemOverwrite()`, …)
+ * and it wins. The default and the override speak the same vocabulary; the
+ * default is the one you get for free.
+ *
+ *   • `user`   → `allow`  — a human is never blocked by a claim (a claim is a
+ *                           coordination hint among agents, not a lock on people)
+ *   • `agent`  → `reject` — an agent yields to a foreign claim (the no-bypass
+ *                           invariant; the ONLY sanctioned agent override is the
+ *                           privileged `claim.preempt` capability seam, see
+ *                           {@link capabilityPreemptPolicy})
+ *   • `system` → `reject` — automation / backend (`sk_`) writers SERIALIZE
+ *                           through claims by default like agents do, so a server
+ *                           job can't silently steamroll a held row. Opt a model
+ *                           in with `systemOverwrite()` when that's wanted.
+ *
+ * Scope note: only `user` is allowed by default — that is the exact Law 7
+ * decision ("a human is never blocked"). `system` is deliberately NOT a
+ * free-bypass: `sk_` keys are full-access backend credentials, and a foundational
+ * contract (claim serialization / the retry-storm guard) depends on them
+ * respecting claims unless a model says otherwise.
+ *
+ * `stale_context` conflicts honor the committer's declared `onStale` intent:
  *
  *   • `'notify'` → notify + hold (op withheld; the actor resolves)
  *   • anything else (incl. `'reject'`, absent) → reject
  *
- * `'overwrite'` never reaches a policy — it's a hard opt-out resolved before
- * detection. This preserves the legacy always-reject default for callers that
- * don't opt into `notify`.
+ * `'overwrite'` never reaches a policy on the stale path — it's a hard opt-out
+ * resolved before detection.
  */
 export declare const defaultPolicy: (conflict: Conflict) => ConflictDecision;
 /**
@@ -172,8 +194,10 @@ export interface ConflictAxis {
  * synchronous (no I/O), so it runs on either side of the schema-agnostic
  * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
  *
- *   - undefined   → the engine default (`defaultPolicy`: reject; honor
- *                   `onStale: 'notify'` on a stale write)
+ *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human (`user`)
+ *                   committer is allowed (never blocked); `agent` and `system`
+ *                   reject on a `claim_held`; on a stale write, honor
+ *                   `onStale: 'notify'`)
  *   - `overwrite` → `allow` — the write wins / the committer is never blocked
  *   - `reject`    → `reject` — the committer yields
  *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);

package/dist/policy/types.js

@@ -7,18 +7,40 @@
  * Adding new shapes is additive on the discriminated union.
  */
 /**
- * Default policy.
+ * Default policy — **Law 7 (the human is the principal) is the engine-wide
+ * default, not an opt-in.**
  *
- * `claim_held` conflicts always reject (a foreign claim is honored unless a
- * privileged policy preempts). `stale_context` conflicts honor the committer's
- * declared `onStale` intent:
+ * A `claim_held` conflict resolves by the COMMITTER's kind. This default is, by
+ * construction, identical to `coordination(humansOverwrite())` applied to every
+ * model — so a developer who wants different behaviour just declares the conflict
+ * axis on that model (`humansReject()`, `humansNotify()`, `systemOverwrite()`, …)
+ * and it wins. The default and the override speak the same vocabulary; the
+ * default is the one you get for free.
+ *
+ *   • `user`   → `allow`  — a human is never blocked by a claim (a claim is a
+ *                           coordination hint among agents, not a lock on people)
+ *   • `agent`  → `reject` — an agent yields to a foreign claim (the no-bypass
+ *                           invariant; the ONLY sanctioned agent override is the
+ *                           privileged `claim.preempt` capability seam, see
+ *                           {@link capabilityPreemptPolicy})
+ *   • `system` → `reject` — automation / backend (`sk_`) writers SERIALIZE
+ *                           through claims by default like agents do, so a server
+ *                           job can't silently steamroll a held row. Opt a model
+ *                           in with `systemOverwrite()` when that's wanted.
+ *
+ * Scope note: only `user` is allowed by default — that is the exact Law 7
+ * decision ("a human is never blocked"). `system` is deliberately NOT a
+ * free-bypass: `sk_` keys are full-access backend credentials, and a foundational
+ * contract (claim serialization / the retry-storm guard) depends on them
+ * respecting claims unless a model says otherwise.
+ *
+ * `stale_context` conflicts honor the committer's declared `onStale` intent:
  *
  *   • `'notify'` → notify + hold (op withheld; the actor resolves)
  *   • anything else (incl. `'reject'`, absent) → reject
  *
- * `'overwrite'` never reaches a policy — it's a hard opt-out resolved before
- * detection. This preserves the legacy always-reject default for callers that
- * don't opt into `notify`.
+ * `'overwrite'` never reaches a policy on the stale path — it's a hard opt-out
+ * resolved before detection.
  */
 // Typed by its real SYNCHRONOUS shape (via `satisfies`) rather than the
 // async-permissive `ConflictPolicy` alias, so sync callers like
@@ -26,8 +48,15 @@
 // `ConflictDecision` back (not `… | Promise<…>`). Still assignable to
 // `ConflictPolicy` everywhere it's used as a policy.
 export const defaultPolicy = ((conflict) => {
-    if (conflict.kind !== 'stale_context') {
-        return { action: 'reject', reason: 'claim_conflict' };
+    if (conflict.kind === 'claim_held') {
+        // Law 7 universal default: a human (`user`) is never blocked; agents AND
+        // system actors yield. Keeping every non-`user` kind on `reject` here is
+        // what makes the no-bypass invariant hold even on the registry/default
+        // resolution path (which, unlike the declared-axis path, has no separate
+        // agent-degradation guard).
+        return conflict.committer.kind === 'user'
+            ? { action: 'allow', note: 'principal:not-blocked' }
+            : { action: 'reject', reason: 'claim_conflict' };
     }
     return conflict.requestedMode === 'notify'
         ? { action: 'notify', reason: 'stale_notify_hold' }
@@ -53,8 +82,10 @@ export const capabilityPreemptPolicy = (conflict) => {
  * synchronous (no I/O), so it runs on either side of the schema-agnostic
  * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
  *
- *   - undefined   → the engine default (`defaultPolicy`: reject; honor
- *                   `onStale: 'notify'` on a stale write)
+ *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human (`user`)
+ *                   committer is allowed (never blocked); `agent` and `system`
+ *                   reject on a `claim_held`; on a stale write, honor
+ *                   `onStale: 'notify'`)
  *   - `overwrite` → `allow` — the write wins / the committer is never blocked
  *   - `reject`    → `reject` — the committer yields
  *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);

package/dist/react/AbloProvider.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from 'react';
 import type { SchemaRecord } from '../schema/schema.js';
 import { Ablo } from '../client/Ablo.js';
-import type { ActiveClaim, Peer } from '../types/streams.js';
+import type { Claim, Peer } from '../types/streams.js';
 import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../sync/participants.js';
 import { type SyncStoreContract } from './context.js';
 /**
@@ -154,7 +154,7 @@ export interface UseWatchReturn {
     /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
     readonly peers: ReadonlyArray<Peer>;
     /** Active claim claims by peers (`participant.claims.others`), bridged to React. */
-    readonly claims: ReadonlyArray<ActiveClaim>;
+    readonly claims: ReadonlyArray<Claim>;
     readonly status: ParticipantStatus;
     readonly error: Error | null;
 }

package/dist/schema/ddl.d.ts

@@ -65,6 +65,42 @@ export declare function snakeToCamel(identifier: string): string;
 /** Quote an identifier (defense-in-depth; inputs are already slug/snake). */
 export declare function q(identifier: string): string;
 export declare function sqlType(fieldType: ModelJSON['fields'][string]['type']): string;
+/**
+ * Detect and repair `field.json()` columns that exist in the live database as a
+ * NON-jsonb type, and emit a salvaging in-place `ALTER … TYPE jsonb`.
+ *
+ * Why this is needed: provisioning uses `ADD COLUMN IF NOT EXISTS` and
+ * `CREATE TABLE IF NOT EXISTS` (idempotent by design). When `ablo push` adopts
+ * a table/column that PRE-EXISTS with a different type — e.g. a `content TEXT`
+ * column from a legacy table — the additive DDL is a no-op and the column
+ * silently stays `text`. The pure schema-to-schema differ
+ * ({@link generateMigrationPlan}) can't see this: the schema says `json` on
+ * both sides, so it emits no change. The drift is only visible by INTROSPECTING
+ * the live database and comparing to the declared type — the drizzle-kit
+ * `pull` discipline. A `json` value bound to a `text` column corrupts to the
+ * literal `"[object Object]"`, so leaving the drift unrepaired is silent data
+ * loss.
+ *
+ * The cast is SALVAGING, never aborting (Postgres won't auto-cast text→jsonb;
+ * invalid rows would otherwise fail the whole ALTER): a row that `IS JSON`
+ * parses to jsonb, anything else (including already-corrupted
+ * `"[object Object]"`) is wrapped as a jsonb string via `to_jsonb`, and NULL
+ * stays NULL. The `IS JSON` predicate requires Postgres 16+ (the fleet runs
+ * 17); on an older engine the ALTER fails LOUD with a structured
+ * `migration_failed` rather than silently — acceptable, since silent corruption
+ * is the thing we're eliminating. See
+ * https://echobind.com/post/safely-alter-postgres-columns-with-using.
+ *
+ * Pure + idempotent: emits a statement ONLY for a json field whose live column
+ * type is present and not already `jsonb`/`json`. A correctly-provisioned schema
+ * yields zero statements, so this is a no-op on every push after the first
+ * repair. Columns absent from `liveColumnTypes` are left to the additive
+ * provisioner (which adds them as jsonb).
+ *
+ * @param liveColumnTypes table name → (column name → information_schema
+ *   `data_type`), as introspected from the target schema.
+ */
+export declare function generateJsonColumnReconciliation(schema: SchemaJSON, liveColumnTypes: ReadonlyMap<string, ReadonlyMap<string, string>>, targetSchema: string): string[];
 /**
  * Build the additive, idempotent provisioning plan for an app. Pure — no DB
  * access.

package/dist/schema/ddl.js

@@ -66,6 +66,72 @@ export function sqlType(fieldType) {
     }
 }
 const BASE_COLUMNS = new Set(['id', 'organization_id', 'created_by', 'created_at', 'updated_at']);
+// ── JSON column drift reconciliation ─────────────────────────────────────────
+/**
+ * Detect and repair `field.json()` columns that exist in the live database as a
+ * NON-jsonb type, and emit a salvaging in-place `ALTER … TYPE jsonb`.
+ *
+ * Why this is needed: provisioning uses `ADD COLUMN IF NOT EXISTS` and
+ * `CREATE TABLE IF NOT EXISTS` (idempotent by design). When `ablo push` adopts
+ * a table/column that PRE-EXISTS with a different type — e.g. a `content TEXT`
+ * column from a legacy table — the additive DDL is a no-op and the column
+ * silently stays `text`. The pure schema-to-schema differ
+ * ({@link generateMigrationPlan}) can't see this: the schema says `json` on
+ * both sides, so it emits no change. The drift is only visible by INTROSPECTING
+ * the live database and comparing to the declared type — the drizzle-kit
+ * `pull` discipline. A `json` value bound to a `text` column corrupts to the
+ * literal `"[object Object]"`, so leaving the drift unrepaired is silent data
+ * loss.
+ *
+ * The cast is SALVAGING, never aborting (Postgres won't auto-cast text→jsonb;
+ * invalid rows would otherwise fail the whole ALTER): a row that `IS JSON`
+ * parses to jsonb, anything else (including already-corrupted
+ * `"[object Object]"`) is wrapped as a jsonb string via `to_jsonb`, and NULL
+ * stays NULL. The `IS JSON` predicate requires Postgres 16+ (the fleet runs
+ * 17); on an older engine the ALTER fails LOUD with a structured
+ * `migration_failed` rather than silently — acceptable, since silent corruption
+ * is the thing we're eliminating. See
+ * https://echobind.com/post/safely-alter-postgres-columns-with-using.
+ *
+ * Pure + idempotent: emits a statement ONLY for a json field whose live column
+ * type is present and not already `jsonb`/`json`. A correctly-provisioned schema
+ * yields zero statements, so this is a no-op on every push after the first
+ * repair. Columns absent from `liveColumnTypes` are left to the additive
+ * provisioner (which adds them as jsonb).
+ *
+ * @param liveColumnTypes table name → (column name → information_schema
+ *   `data_type`), as introspected from the target schema.
+ */
+export function generateJsonColumnReconciliation(schema, liveColumnTypes, targetSchema) {
+    const qs = q(targetSchema);
+    const statements = [];
+    for (const [key, model] of Object.entries(schema.models)) {
+        const table = model.tableName ?? key;
+        const liveCols = liveColumnTypes.get(table);
+        if (!liveCols)
+            continue; // table not provisioned yet — nothing to reconcile
+        const qt = `${qs}.${q(table)}`;
+        for (const [fieldName, meta] of Object.entries(model.fields)) {
+            if (meta.type !== 'json')
+                continue;
+            const col = meta.column ?? camelToSnake(fieldName);
+            const liveType = liveCols.get(col);
+            if (liveType === undefined)
+                continue; // column absent — provisioner adds jsonb
+            if (liveType === 'jsonb' || liveType === 'json')
+                continue; // already correct
+            const c = q(col);
+            statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${c} TYPE jsonb USING (\n` +
+                `  CASE\n` +
+                `    WHEN ${c} IS NULL THEN NULL\n` +
+                `    WHEN ${c}::text IS JSON THEN ${c}::text::jsonb\n` +
+                `    ELSE to_jsonb(${c}::text)\n` +
+                `  END\n` +
+                `);`);
+        }
+    }
+    return statements;
+}
 // ── Foreign keys (relation-driven, sync-safe) ────────────────────────────────
 /**
  * A Postgres-identifier-safe constraint name ≤63 bytes. When the natural

package/dist/schema/index.d.ts

@@ -33,7 +33,7 @@ export { mutable, readOnly, type SugarOptions } from './sugar.js';
 export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels } from './select.js';
-export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
+export { generateProvisionPlan, generateMigrationPlan, generateJsonColumnReconciliation, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, type BackfillValue, type MigrationStep, type FieldChanges, type FieldColumnChange, type FieldTypeChange, type NullabilityChange, type EnumValuesChange, type IndexChange, type CastSafety, type FieldType, type RenameHints, type MigrationSignal, type MigrationClassification, type WarningCode, type BlockerCode, } from './diff.js';
 export { generateTypes } from './generate.js';
 export { query, defineQueries, type QueryDef, type QueryRecord, type Queries, type InferQueryInput, type InferQueryResult, } from './queries.js';

package/dist/schema/index.js

@@ -55,7 +55,7 @@ export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash,
 // Schema projection — derive an app's subset from one canonical schema.
 export { selectModels } from './select.js';
 // Schema → Postgres DDL (pure; shared by the hosted server and the CLI)
-export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, } from './ddl.js';
+export { generateProvisionPlan, generateMigrationPlan, generateJsonColumnReconciliation, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, } from './ddl.js';
 // Schema diff + migration planning (pure; SQL emission lowered by ddl.ts)
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, } from './diff.js';
 // Schema → TypeScript type emission (the `generate` half; pure)

package/dist/surface.d.ts

@@ -23,7 +23,7 @@ export declare const PUBLIC_MODEL_VERBS: readonly ["retrieve", "list", "get", "g
 export declare const PUBLIC_LIST_OPTION_KEYS: readonly ["where", "filter", "orderBy", "limit", "offset", "state"];
 /** Public keys of `AbloOptions`. `schema` is required; the rest are optional
  *  (the locked happy path is `Ablo({ schema, apiKey, databaseUrl, transport })`). */
-export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "databaseUrl", "persistence", "transport", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
+export declare const PUBLIC_ABLO_OPTION_KEYS: readonly ["schema", "apiKey", "databaseUrl", "persistence", "transport", "debug", "logLevel", "authToken", "baseURL", "fetch", "defaultHeaders", "defaultQuery", "dangerouslyAllowBrowser"];
 export type ModelVerb = (typeof PUBLIC_MODEL_VERBS)[number];
 export type ListOptionKey = (typeof PUBLIC_LIST_OPTION_KEYS)[number];
 export type AbloOptionKey = (typeof PUBLIC_ABLO_OPTION_KEYS)[number];

package/dist/surface.js

@@ -51,6 +51,8 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
     'databaseUrl',
     'persistence',
     'transport',
+    'debug',
+    'logLevel',
     'authToken',
     'baseURL',
     'fetch',

package/dist/sync/HydrationCoordinator.js

@@ -171,7 +171,11 @@ export class HydrationCoordinator {
     async fetchFromNetwork(modelName, typename, clauses, options) {
         const networkRows = await this.queryNetwork(modelName, clauses, options);
         const networkModels = networkRows
-            .map((raw) => this.hydrateOne(raw, typename))
+            // Strict: a row the SERVER returned whose typename this client never
+            // registered is a genuine schema collision (the org's pushed schema
+            // differs from local) — throw it here, naming the cause, rather than
+            // silently dropping the row and failing downstream as `entity_not_found`.
+            .map((raw) => this.hydrateOne(raw, typename, { strict: true }))
             .filter((m) => m !== null);
         if (networkModels.length > 0) {
             this.opts.objectPool.addBatch(networkModels, ModelScope.live);
@@ -288,7 +292,7 @@ export class HydrationCoordinator {
     getModelDef(modelName) {
         return this.opts.schema.models?.[modelName];
     }
-    hydrateOne(raw, typename) {
+    hydrateOne(raw, typename, opts) {
         if (!raw || typeof raw !== 'object')
             return null;
         const obj = raw;
@@ -321,7 +325,7 @@ export class HydrationCoordinator {
         // re-populate it). The typename comes from the schema relation
         // (`'SlideLayer'`, `'SlideLayoutLayer'`, etc.) so no guessing involved.
         const stamped = this.stampTypename(obj, typename);
-        return this.opts.objectPool.createFromData(stamped);
+        return this.opts.objectPool.createFromData(stamped, undefined, opts);
     }
     /**
      * Stamp `__typename` onto a row when it's known (from the schema's

package/dist/sync/SyncWebSocket.d.ts

@@ -179,7 +179,7 @@ export interface PresenceUpdateEvent {
     participantKind?: string;
     timestamp?: number;
     /** Server stamps every presence frame with this participant's open
-     *  claim claims so peers see them without a separate channel. Wire
+     *  claims so peers see them without a separate channel. Wire
      *  shape mirrors `apps/sync-server/src/hub/types.ts Claim`. */
     activeClaims?: Array<{
         claimId: string;
@@ -192,7 +192,7 @@ export interface PresenceUpdateEvent {
             startColumn?: number;
             endColumn?: number;
         };
-        action: string;
+        reason: string;
         field?: string;
         meta?: Record<string, unknown>;
         declaredAt: number;
@@ -490,6 +490,15 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * so a bad notification never sinks an otherwise-successful commit.
      */
     private parseNotifications;
+    /**
+     * Single instrumentation point for claim events. Every `claim_*` frame routes
+     * through here so a developer debugging a collision gets one consistent trace
+     * — a console line AND a structured capture — without each dispatch case
+     * re-deriving the row/holder shape. The wire payload is loosely typed
+     * (`Record<string, unknown>`), so this is the one place that narrows it into
+     * a {@link ClaimEvent}.
+     */
+    private recordClaim;
     sendCommit(operations: ReadonlyArray<MutationOperation>, clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): Promise<CommitAck>;
     /**
      * Send a commit frame without waiting for `mutation_result`.

package/dist/sync/SyncWebSocket.js

@@ -11,7 +11,8 @@ import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
 import { flushOfflineQueueOnce } from './OfflineFlush.js';
 import { AbloConnectionError, AbloError, CapabilityError, SyncSessionError, errorFromWire, toAbloError, } from '../errors.js';
-import { subscriptionAckPayloadSchema, staleNotificationSchema, } from '../coordination/schema.js';
+import { subscriptionAckPayloadSchema, staleNotificationSchema, wireParticipantKindSchema, } from '../coordination/schema.js';
+import { formatClaim, formatConflict } from '../coordination/trace.js';
 import { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from '../auth/credentialSource.js';
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
@@ -177,7 +178,7 @@ export class SyncWebSocket extends EventEmitter {
         // which is unreliable but the only signal available; in Node it returns true
         // (assume online) so the sidecar/agent path doesn't short-circuit here.
         if (!getContext().onlineStatus.isOnline()) {
-            getContext().logger.warn('onlineStatus reports offline, but attempting connection anyway');
+            getContext().logger.debug('onlineStatus reports offline, but attempting connection anyway');
         }
         this.isConnecting = true;
         this.isManualClose = false;
@@ -338,8 +339,23 @@ export class SyncWebSocket extends EventEmitter {
                             // the advisory signal so an agent loop can self-heal, AND resolve
                             // the receipt with it (the commit still succeeded).
                             if (notifications && notifications.length > 0) {
+                                const txId = typeof clientTxId === 'string' ? clientTxId : '';
+                                const event = {
+                                    clientTxId: txId,
+                                    rows: notifications.map((n) => ({
+                                        model: n.model,
+                                        id: n.id,
+                                        fields: n.conflictingFields,
+                                        writtenBy: n.writtenBy?.kind,
+                                    })),
+                                };
+                                const message = formatConflict(event);
+                                const ctx = getContext();
+                                ctx.logger.warn(message);
+                                ctx.observability.breadcrumb(message, 'sync.coordination', 'warning');
+                                ctx.observability.captureConflict(event);
                                 this.emit('conflict:notified', {
-                                    clientTxId: typeof clientTxId === 'string' ? clientTxId : '',
+                                    clientTxId: txId,
                                     notifications,
                                 });
                             }
@@ -493,6 +509,7 @@ export class SyncWebSocket extends EventEmitter {
                         // inactive server-side by the time this arrives.
                         const p = message.payload ?? {};
                         if (typeof p.claimId === 'string') {
+                            this.recordClaim('expired', p);
                             this.emit('claim_expired', { claimId: p.claimId });
                         }
                         break;
@@ -502,33 +519,40 @@ export class SyncWebSocket extends EventEmitter {
                         // already claimed by another participant. Forward the
                         // payload as-is — the ClaimStream consumer interprets
                         // the conflict shape (peerId, target, etc.).
+                        this.recordClaim('rejected', message.payload ?? {});
                         this.emit('claim_rejected', message.payload ?? {});
                         break;
                     }
                     case 'claim_acquired': {
                         // Opt-in fair queue: the target was free, so the lease is ours
                         // immediately (no waiting). Payload carries { claimId, target }.
+                        this.recordClaim('acquired', message.payload ?? {});
                         this.emit('claim_acquired', message.payload ?? {});
                         break;
                     }
                     case 'claim_queue': {
-                        // Per-entity wait-queue snapshot for reactive `queue(id)`.
+                        // Per-entity wait-queue snapshot for reactive `queue(id)`. Not a
+                        // single claim's state change, so it isn't logged — the per-claim
+                        // `queued`/`granted` events already tell that story.
                         this.emit('claim_queue', message.payload ?? {});
                         break;
                     }
                     case 'claim_queued': {
                         // Opt-in fair queue: our claim is waiting in line. Payload
                         // carries { claimId, target, position }.
+                        this.recordClaim('queued', message.payload ?? {});
                         this.emit('claim_queued', message.payload ?? {});
                         break;
                     }
                     case 'claim_granted': {
                         // Our queued claim reached the head — the lease is now ours.
+                        this.recordClaim('granted', message.payload ?? {});
                         this.emit('claim_granted', message.payload ?? {});
                         break;
                     }
                     case 'claim_lost': {
                         // A held/granted claim was taken from us (TTL lapse, revoke).
+                        this.recordClaim('lost', message.payload ?? {});
                         this.emit('claim_lost', message.payload ?? {});
                         break;
                     }
@@ -872,6 +896,46 @@ export class SyncWebSocket extends EventEmitter {
         }
         return out.length > 0 ? out : undefined;
     }
+    /**
+     * Single instrumentation point for claim events. Every `claim_*` frame routes
+     * through here so a developer debugging a collision gets one consistent trace
+     * — a console line AND a structured capture — without each dispatch case
+     * re-deriving the row/holder shape. The wire payload is loosely typed
+     * (`Record<string, unknown>`), so this is the one place that narrows it into
+     * a {@link ClaimEvent}.
+     */
+    recordClaim(phase, payload) {
+        const str = (v) => typeof v === 'string' ? v : undefined;
+        // Targets arrive flat ({ entityType, entityId }) or nested under `target`.
+        const target = payload.target && typeof payload.target === 'object'
+            ? payload.target
+            : payload;
+        const kind = wireParticipantKindSchema.safeParse(payload.participantKind);
+        const event = {
+            phase,
+            claimId: str(payload.claimId),
+            model: str(target.entityType) ?? str(target.model),
+            id: str(target.entityId) ?? str(target.id),
+            field: str(target.field),
+            actor: str(payload.actor) ?? str(payload.heldBy),
+            participantKind: kind.success ? kind.data : undefined,
+            position: typeof payload.position === 'number' ? payload.position : undefined,
+            reason: str(payload.policyReason) ?? str(payload.reason),
+        };
+        const message = formatClaim(event);
+        // A rejection or lost lease is the collision a developer is actively
+        // debugging → warn (shows at the default log level). The routine events
+        // (acquired/queued/granted/expired) are debug-only so they never drown the
+        // console until you opt in with `new Ablo({ debug: true })`.
+        const isCollision = phase === 'rejected' || phase === 'lost';
+        const ctx = getContext();
+        if (isCollision)
+            ctx.logger.warn(message);
+        else
+            ctx.logger.debug(message);
+        ctx.observability.breadcrumb(message, 'sync.coordination', isCollision ? 'warning' : 'info');
+        ctx.observability.captureClaim(event);
+    }
     sendCommit(operations, clientTxId, timeoutMs = 15_000, causedByTaskId, reads) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             return Promise.reject(this.notConnectedError('commit'));

package/dist/sync/awaitClaimGrant.js

@@ -13,6 +13,7 @@
  * fake; `SyncWebSocket` satisfies it structurally.
  */
 import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
+import { getContext } from '../context.js';
 export function awaitClaimGrant(transport, claimId, options) {
     return new Promise((resolve, reject) => {
         const unsubs = [];
@@ -28,12 +29,18 @@ export function awaitClaimGrant(transport, claimId, options) {
         // we waited in line, and reached the head → `claim_granted`. Either frame
         // means the lease is now ours; `waited` records which path it was.
         unsubs.push(transport.subscribe('claim_acquired', (p) => {
-            if (p?.claimId === claimId)
+            if (p?.claimId === claimId) {
+                getContext().logger.debug(`claim: acquired ${claimId} (target was free)`);
                 settle(() => resolve({ waited: false }));
+            }
         }));
         unsubs.push(transport.subscribe('claim_granted', (p) => {
-            if (p?.claimId === claimId)
+            if (p?.claimId === claimId) {
+                // Promoted to the head of the line — the creator's "it's the agent's
+                // turn now" moment after waiting behind a holder.
+                getContext().logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
                 settle(() => resolve({ waited: true }));
+            }
         }));
         if (options?.maxQueueDepth !== undefined) {
             const max = options.maxQueueDepth;