@abloatai/ablo 0.24.0 → 0.26.0

package/dist/transactions/deltaConfirmation.js

@@ -0,0 +1,223 @@
+/**
+ * Delta-confirmation tracking — the queue's "did my write's echo arrive?"
+ * machinery, lifted out of `TransactionQueue.ts` as a stateful leaf.
+ *
+ * Owns the ack watermark (via the shared `SyncPosition`), the per-transaction
+ * confirmation timeout map, and the retry-with-backoff/reconciliation policy
+ * for `awaiting_delta` transactions. Talks back to the queue through the
+ * minimal `DeltaConfirmationContext` interface (never the host class type),
+ * so the leaf stays cycle-free and testable in isolation.
+ */
+import { getContext } from '../context.js';
+export class DeltaConfirmationTracker {
+    ctx;
+    // Delta confirmation retry config (Replicache-style exponential backoff)
+    // Max retries before requesting full reconciliation
+    static DELTA_MAX_RETRIES = 5;
+    // Initial timeout (first attempt)
+    static DELTA_INITIAL_TIMEOUT_MS = 30_000;
+    // Max timeout cap (like Replicache's maxDelayMs of 60s)
+    static DELTA_MAX_TIMEOUT_MS = 120_000;
+    // LINEAR PATTERN: Track delta confirmation timeouts for awaiting_delta transactions
+    // Following Replicache/PowerSync pattern: retry with backoff instead of rolling back
+    deltaConfirmationTimeouts = new Map();
+    // Track retry attempts per transaction for exponential backoff
+    deltaConfirmationRetries = new Map();
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** Applied-cursor alias, kept so the read sites below stay legible. */
+    get lastSeenSyncId() {
+        return this.ctx.position.applied;
+    }
+    noteAck(lastSyncId) {
+        this.ctx.position.noteAck(lastSyncId);
+    }
+    /**
+     * LINEAR PATTERN: Confirm all awaiting transactions when delta with syncId >= threshold arrives.
+     * This replaces clientMutationId echoing - transactions are confirmed by sync ID threshold.
+     * @param syncId - The sync ID of the received delta
+     */
+    onDeltaReceived(syncId) {
+        // Cursor advancing happens where the delta is APPLIED (the store calls
+        // position.advanceApplied / advancePersisted); this hook only resolves
+        // confirmation thresholds against the incoming id.
+        const awaitingTxs = this.ctx.store.getByStatus('awaiting_delta');
+        const executingTxs = this.ctx.store.getByStatus('executing');
+        // Debug: Show state when delta arrives
+        if (awaitingTxs.length > 0 || executingTxs.length > 0) {
+            getContext().logger.debug('tx:delta_received', {
+                syncId,
+                lastSeenSyncId: this.lastSeenSyncId,
+                awaitingCount: awaitingTxs.length,
+                executingCount: executingTxs.length,
+                awaitingThresholds: awaitingTxs.map((tx) => ({
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                    needed: tx.syncIdNeededForCompletion,
+                    willConfirm: tx.syncIdNeededForCompletion !== undefined && syncId >= tx.syncIdNeededForCompletion,
+                })),
+            });
+        }
+        // Fast path: no awaiting transactions
+        if (awaitingTxs.length === 0)
+            return;
+        let confirmedCount = 0;
+        for (const tx of awaitingTxs) {
+            // Confirm if this delta's ID meets or exceeds the threshold
+            if (tx.syncIdNeededForCompletion !== undefined && syncId >= tx.syncIdNeededForCompletion) {
+                this.cancelDeltaConfirmationTimeout(tx.id);
+                this.ctx.store.updateStatus(tx.id, 'completed');
+                this.ctx.emit('transaction:completed', tx);
+                this.ctx.emit(`transaction:completed:${tx.id}`, tx);
+                this.ctx.optimisticUpdates.delete(tx.id);
+                confirmedCount++;
+                getContext().logger.debug('tx:confirm_via_delta', {
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                    neededSyncId: tx.syncIdNeededForCompletion,
+                    receivedSyncId: syncId,
+                });
+            }
+        }
+        // Log batch summary only if we confirmed something
+        if (confirmedCount > 0) {
+            // Use warn for staging visibility when transactions confirm
+            getContext().observability.breadcrumb('Transactions confirmed via delta', 'sync.transaction', 'info', {
+                count: confirmedCount,
+                syncId,
+                remainingAwaiting: awaitingTxs.length - confirmedCount,
+            });
+        }
+    }
+    // REPLICACHE/POWERSYNC PATTERN: Schedule delta confirmation with retry + reconciliation
+    // Instead of rolling back on timeout (which destroys confirmed server state),
+    // retry with exponential backoff and request reconciliation to catch up on missed deltas.
+    // Only rollback on explicit server rejection, never on timeout.
+    scheduleDeltaConfirmationTimeout(tx, timeoutMs) {
+        // Cancel any existing timeout for this transaction
+        this.cancelDeltaConfirmationTimeout(tx.id);
+        // NB: deliberately NOT an async callback — the body is fully synchronous,
+        // and `setTimeout(async …)` turns any throw into an unhandled promise
+        // rejection instead of a catchable synchronous error.
+        const timeoutHandle = setTimeout(() => {
+            const currentTx = this.ctx.store.get(tx.id);
+            if (!currentTx || currentTx.status !== 'awaiting_delta') {
+                this.deltaConfirmationRetries.delete(tx.id);
+                return; // Already confirmed or failed
+            }
+            // If disconnected, re-schedule with same timeout (no backoff while offline)
+            if (!this.ctx.isConnected()) {
+                // Self-healing: re-schedule the confirmation wait while offline, no
+                // consumer action needed → debug.
+                getContext().logger.debug('[TransactionQueue] Timeout fired while disconnected - re-scheduling', {
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                });
+                this.deltaConfirmationTimeouts.delete(tx.id);
+                this.scheduleDeltaConfirmationTimeout(tx, timeoutMs);
+                return;
+            }
+            const retryCount = this.deltaConfirmationRetries.get(tx.id) ?? 0;
+            const diagnosis = this.lastSeenSyncId === 0
+                ? 'No deltas received - delta pipeline may be broken'
+                : currentTx.syncIdNeededForCompletion &&
+                    this.lastSeenSyncId < currentTx.syncIdNeededForCompletion
+                    ? 'Delta not yet received - may be lost or delayed'
+                    : 'Delta should have confirmed - possible race condition';
+            getContext().observability.captureReconciliation({
+                reason: 'delta_timeout',
+                model: tx.modelName,
+                modelId: tx.modelId,
+                syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                lastSeenSyncId: this.lastSeenSyncId,
+                retryCount,
+                connectionState: this.ctx.isConnected() ? 'connected' : 'disconnected',
+            });
+            if (retryCount < DeltaConfirmationTracker.DELTA_MAX_RETRIES) {
+                // RETRY: Request reconciliation and re-schedule with exponential backoff
+                // The server already committed this mutation — we just need the delta to arrive
+                this.deltaConfirmationRetries.set(tx.id, retryCount + 1);
+                this.deltaConfirmationTimeouts.delete(tx.id);
+                // Exponential backoff: 30s → 60s → 120s → 120s → 120s (capped)
+                const nextTimeout = Math.min(timeoutMs * 2, DeltaConfirmationTracker.DELTA_MAX_TIMEOUT_MS);
+                // Emit reconciliation request so SyncedStore can cycle the WebSocket
+                // to trigger delta catch-up from the server
+                this.ctx.emit('reconciliation:needed', {
+                    reason: 'delta_confirmation_timeout',
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                    lastSeenSyncId: this.lastSeenSyncId,
+                    retryCount: retryCount + 1,
+                });
+                // Self-healing retry with backoff — the server already committed; we're
+                // just waiting on the delta. No consumer action → debug.
+                getContext().logger.debug('[TransactionQueue] Re-scheduling with backoff', {
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                    nextTimeoutMs: nextTimeout,
+                    retry: retryCount + 1,
+                });
+                this.scheduleDeltaConfirmationTimeout(tx, nextTimeout);
+            }
+            else {
+                // LINEAR PATTERN: Retries exhausted — persist to IndexedDB instead of rolling back.
+                // The transaction succeeded on the server (HTTP 200), so the data exists server-side.
+                // Persist the awaiting state so it survives tab close. On next session, the WebSocket
+                // reconnect + delta catch-up will naturally confirm it (like Linear's IndexedDB caching).
+                this.deltaConfirmationRetries.delete(tx.id);
+                this.deltaConfirmationTimeouts.delete(tx.id);
+                getContext().observability.captureDeltaRetryExhausted({
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    retryCount: DeltaConfirmationTracker.DELTA_MAX_RETRIES,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                });
+                // Emit persist event — SyncClient handles the IDB write
+                this.ctx.emit('transaction:persist_awaiting', {
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    operationType: tx.type,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                });
+                // Also request one final reconciliation cycle
+                this.ctx.emit('reconciliation:needed', {
+                    reason: 'delta_retries_exhausted',
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                    lastSeenSyncId: this.lastSeenSyncId,
+                    retryCount: DeltaConfirmationTracker.DELTA_MAX_RETRIES,
+                });
+            }
+        }, timeoutMs);
+        this.deltaConfirmationTimeouts.set(tx.id, timeoutHandle);
+    }
+    // Cancel a pending delta confirmation timeout and clean up retry tracking
+    cancelDeltaConfirmationTimeout(id) {
+        const timeoutHandle = this.deltaConfirmationTimeouts.get(id);
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+            this.deltaConfirmationTimeouts.delete(id);
+        }
+        this.deltaConfirmationRetries.delete(id);
+    }
+    /**
+     * Tear down every armed confirmation timer (30–120s each, one per
+     * in-flight transaction). Called from `TransactionQueue.dispose()` —
+     * without it a disposed queue kept the Node process alive and fired
+     * callbacks against an already-cleared store (T1.19).
+     */
+    dispose() {
+        for (const timeoutHandle of this.deltaConfirmationTimeouts.values()) {
+            clearTimeout(timeoutHandle);
+        }
+        this.deltaConfirmationTimeouts.clear();
+        this.deltaConfirmationRetries.clear();
+    }
+}

package/dist/transactions/optimistic.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Optimistic apply/rollback — the queue's local-first bookkeeping, lifted out
+ * of `TransactionQueue.ts` as a pure leaf. The queue never mutates the pool
+ * itself: applying/rolling back records an entry in the host-owned ledger and
+ * emits `optimistic:*` events that the pool-side listeners act on. These
+ * functions take that ledger plus a minimal emitter interface (never the host
+ * class type), so the rules stay cycle-free and testable in isolation.
+ */
+import type { Model } from '../Model.js';
+import type { MutationInput, Transaction } from './commitPayload.js';
+/** One tracked optimistic mutation: the live model + its pre-image. */
+export interface OptimisticUpdateEntry {
+    model: Model;
+    previousState: MutationInput | null | undefined;
+    transaction: Transaction;
+}
+/** The host's event surface — the only queue capability these rules need. */
+export interface OptimisticEmitter {
+    emit(event: string, payload: unknown): void;
+}
+export declare function applyOptimisticCreate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
+export declare function applyOptimisticUpdate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
+export declare function applyOptimisticDelete(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
+export declare function rollbackOptimistic(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, transaction: Transaction, reason?: string, error?: Error): Promise<void>;

package/dist/transactions/optimistic.js

@@ -0,0 +1,45 @@
+/**
+ * Optimistic apply/rollback — the queue's local-first bookkeeping, lifted out
+ * of `TransactionQueue.ts` as a pure leaf. The queue never mutates the pool
+ * itself: applying/rolling back records an entry in the host-owned ledger and
+ * emits `optimistic:*` events that the pool-side listeners act on. These
+ * functions take that ledger plus a minimal emitter interface (never the host
+ * class type), so the rules stay cycle-free and testable in isolation.
+ */
+export function applyOptimisticCreate(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: null,
+        transaction,
+    });
+    emitter.emit('optimistic:create', { model, transaction });
+}
+export function applyOptimisticUpdate(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: transaction.previousData,
+        transaction,
+    });
+    emitter.emit('optimistic:update', { model, transaction });
+}
+export function applyOptimisticDelete(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: transaction.previousData,
+        transaction,
+    });
+    emitter.emit('optimistic:delete', { model, transaction });
+}
+export async function rollbackOptimistic(optimisticUpdates, emitter, transaction, reason, error) {
+    const optimistic = optimisticUpdates.get(transaction.id);
+    if (!optimistic)
+        return;
+    emitter.emit('optimistic:rollback', {
+        model: optimistic.model,
+        previousState: optimistic.previousState,
+        transaction,
+        reason: reason ?? 'unknown',
+        error,
+    });
+    optimisticUpdates.delete(transaction.id);
+}

package/dist/transactions/persistedReplay.d.ts

@@ -0,0 +1,93 @@
+/**
+ * persistedReplay — the Zod boundary for IDB → commit replay (T1.8).
+ *
+ * Rows read back from the persisted-transaction store were written by a
+ * PREVIOUS session — possibly by an older SDK version, possibly corrupted.
+ * Spreading them straight into a `Transaction` re-entered the commit path
+ * with zero validation. These schemas validate exactly the fields the queue
+ * (and the offline mutation-queue restore) actually read on replay; rows
+ * that don't parse are DROPPED (and surfaced through observability), never
+ * replayed as garbage commits.
+ *
+ * The same IDB store also holds two NON-replayable row kinds written by
+ * other subsystems — the `'queue'` record (`SyncClient.persistMutationQueue`)
+ * and `'awaiting_delta'` markers (`setupAwaitingTransactionPersistence`).
+ * Those are recognized and skipped silently: they are expected neighbors,
+ * not corruption.
+ */
+import { z } from 'zod';
+import type { Transaction } from './commitPayload.js';
+/**
+ * A replayable persisted transaction — the fields `TransactionQueue`
+ * actually reads when re-enqueueing (id/type/model addressing + payload +
+ * identity context). Everything else is defaulted at rehydration time.
+ */
+export declare const persistedTransactionSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        update: "update";
+        create: "create";
+        delete: "delete";
+        archive: "archive";
+        unarchive: "unarchive";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    modelKey: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    context: z.ZodObject<{
+        userId: z.ZodString;
+        organizationId: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+        teamIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    createdAt: z.ZodOptional<z.ZodNumber>;
+    batchId: z.ZodOptional<z.ZodString>;
+    writeOptions: z.ZodOptional<z.ZodObject<{
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    localOnly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export type PersistedReplayableTransaction = z.infer<typeof persistedTransactionSchema>;
+/** Whether a persisted row belongs to another subsystem (skip, don't flag). */
+export declare function isNonReplayablePersistedRow(row: unknown): boolean;
+/**
+ * Validate + rehydrate one persisted row into a replayable `Transaction`,
+ * or `null` when the row doesn't parse. Missing bookkeeping fields are
+ * re-derived exactly like a fresh staging would derive them.
+ */
+export declare function deserializePersistedTransaction(row: unknown): Transaction | null;
+/**
+ * One entry of the persisted offline mutation queue (the `'queue'` row's
+ * `mutations` array) — the fields `SyncClient.restoreMutationQueue` reads.
+ */
+export declare const persistedMutationSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        update: "update";
+        create: "create";
+        delete: "delete";
+        archive: "archive";
+    }>;
+    modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    modelName: z.ZodString;
+    timestamp: z.ZodString;
+    writeOptions: z.ZodOptional<z.ZodObject<{
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type PersistedQueuedMutation = z.infer<typeof persistedMutationSchema>;

package/dist/transactions/persistedReplay.js

@@ -0,0 +1,105 @@
+/**
+ * persistedReplay — the Zod boundary for IDB → commit replay (T1.8).
+ *
+ * Rows read back from the persisted-transaction store were written by a
+ * PREVIOUS session — possibly by an older SDK version, possibly corrupted.
+ * Spreading them straight into a `Transaction` re-entered the commit path
+ * with zero validation. These schemas validate exactly the fields the queue
+ * (and the offline mutation-queue restore) actually read on replay; rows
+ * that don't parse are DROPPED (and surfaced through observability), never
+ * replayed as garbage commits.
+ *
+ * The same IDB store also holds two NON-replayable row kinds written by
+ * other subsystems — the `'queue'` record (`SyncClient.persistMutationQueue`)
+ * and `'awaiting_delta'` markers (`setupAwaitingTransactionPersistence`).
+ * Those are recognized and skipped silently: they are expected neighbors,
+ * not corruption.
+ */
+import { z } from 'zod';
+import { computePriorityScore, normalizeModelKey } from './commitPayload.js';
+/** Write-option subset persisted per transaction / mutation. */
+const persistedWriteOptionsSchema = z
+    .object({
+    readAt: z.number().nullable().optional(),
+    onStale: z.enum(['reject', 'overwrite', 'notify']).nullable().optional(),
+    idempotencyKey: z.string().optional(),
+    label: z.string().optional(),
+})
+    .passthrough();
+/**
+ * A replayable persisted transaction — the fields `TransactionQueue`
+ * actually reads when re-enqueueing (id/type/model addressing + payload +
+ * identity context). Everything else is defaulted at rehydration time.
+ */
+export const persistedTransactionSchema = z
+    .object({
+    id: z.string().min(1),
+    type: z.enum(['create', 'update', 'delete', 'archive', 'unarchive']),
+    modelName: z.string().min(1),
+    modelId: z.string().min(1),
+    modelKey: z.string().min(1).optional(),
+    data: z.record(z.string(), z.unknown()).optional(),
+    previousData: z.record(z.string(), z.unknown()).nullable().optional(),
+    context: z.object({
+        userId: z.string().min(1),
+        organizationId: z.string().min(1),
+        role: z.string().optional(),
+        teamIds: z.array(z.string()).optional(),
+    }),
+    createdAt: z.number().optional(),
+    batchId: z.string().optional(),
+    writeOptions: persistedWriteOptionsSchema.optional(),
+    localOnly: z.boolean().optional(),
+})
+    .passthrough();
+/** Row kinds that share the store but are owned by other subsystems. */
+const NON_REPLAYABLE_TYPES = new Set(['queue', 'awaiting_delta']);
+/** Whether a persisted row belongs to another subsystem (skip, don't flag). */
+export function isNonReplayablePersistedRow(row) {
+    return (typeof row === 'object' &&
+        row !== null &&
+        typeof row.type === 'string' &&
+        NON_REPLAYABLE_TYPES.has(row.type));
+}
+/**
+ * Validate + rehydrate one persisted row into a replayable `Transaction`,
+ * or `null` when the row doesn't parse. Missing bookkeeping fields are
+ * re-derived exactly like a fresh staging would derive them.
+ */
+export function deserializePersistedTransaction(row) {
+    const parsed = persistedTransactionSchema.safeParse(row);
+    if (!parsed.success)
+        return null;
+    const tx = parsed.data;
+    return {
+        id: tx.id,
+        type: tx.type,
+        modelName: tx.modelName,
+        modelId: tx.modelId,
+        modelKey: tx.modelKey ?? normalizeModelKey(tx.modelName),
+        ...(tx.data !== undefined ? { data: tx.data } : {}),
+        ...(tx.previousData !== undefined ? { previousData: tx.previousData } : {}),
+        context: tx.context,
+        status: 'pending',
+        createdAt: tx.createdAt ?? Date.now(),
+        attempts: 0,
+        priority: 'normal',
+        priorityScore: computePriorityScore(tx.type, tx.modelName),
+        ...(tx.batchId !== undefined ? { batchId: tx.batchId } : {}),
+        ...(tx.writeOptions !== undefined ? { writeOptions: tx.writeOptions } : {}),
+        ...(tx.localOnly !== undefined ? { localOnly: tx.localOnly } : {}),
+    };
+}
+/**
+ * One entry of the persisted offline mutation queue (the `'queue'` row's
+ * `mutations` array) — the fields `SyncClient.restoreMutationQueue` reads.
+ */
+export const persistedMutationSchema = z
+    .object({
+    type: z.enum(['create', 'update', 'delete', 'archive']),
+    modelData: z.record(z.string(), z.unknown()),
+    modelName: z.string().min(1),
+    timestamp: z.string(),
+    writeOptions: persistedWriteOptionsSchema.optional(),
+})
+    .passthrough();

package/dist/types/index.d.ts

@@ -129,10 +129,10 @@ export interface ModelMetadata {
      * product-neutral: the engine no longer hardcodes which models carry
      * `organizationId` / `createdBy` — the consumer's schema declares it.
      */
-    autoFill?: ReadonlyArray<{
+    autoFill?: readonly {
         field: string;
         from: 'organizationId' | 'userId';
-    }>;
+    }[];
     /**
      * Fields whose absence makes a stored row orphaned. When healing
      * encounters a record missing any of these fields, it returns `null`
@@ -240,4 +240,4 @@ export interface PartialIndexInfo {
     depth: number;
     path: string[];
 }
-export * from "./streams.js";
+export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind, ParticipantRef, JsonValue, ConfirmationState, AgentDelta, Snapshot, ContextChange, ClaimTarget, PresenceTarget, PresenceStream, Activity, Peer, PresenceUpdatePayload, ClaimLeaseOptions, Duration, ClaimOptions, ClaimStream, ClaimLost, ClaimStatus, ClaimWaitOptions, Claim, HeldClaim, } from './streams.js';

package/dist/types/index.js

@@ -63,8 +63,3 @@ export var MutationOperationType;
     MutationOperationType["UNARCHIVE"] = "UNARCHIVE";
     MutationOperationType["UPDATE"] = "UPDATE";
 })(MutationOperationType || (MutationOperationType = {}));
-// Re-export stream + snapshot + principal types for the engine surface
-// (PresenceStream,
-// ClaimStream, Snapshot, etc.) consumed by `Ablo({...}).presence`,
-// `.claims`, `.snapshot()`.
-export * from "./streams.js";

package/dist/types/modelData.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ModelData — the generic record shape for model payloads.
+ *
+ * Lives in its own dependency-free leaf so BOTH `BaseSyncedStore` and
+ * `SyncClient` can import it without importing each other. (The alias
+ * used to live in BaseSyncedStore.ts, which made SyncClient.ts and
+ * BaseSyncedStore.ts a mutual type cycle: the store needs the SyncClient
+ * class type, and SyncClient needed this alias back from the store.)
+ * `BaseSyncedStore` re-exports it, so existing importers are unchanged.
+ */
+/** Generic record type for model data */
+export type ModelData = Record<string, unknown>;

package/dist/types/modelData.js

@@ -0,0 +1,11 @@
+/**
+ * ModelData — the generic record shape for model payloads.
+ *
+ * Lives in its own dependency-free leaf so BOTH `BaseSyncedStore` and
+ * `SyncClient` can import it without importing each other. (The alias
+ * used to live in BaseSyncedStore.ts, which made SyncClient.ts and
+ * BaseSyncedStore.ts a mutual type cycle: the store needs the SyncClient
+ * class type, and SyncClient needed this alias back from the store.)
+ * `BaseSyncedStore` re-exports it, so existing importers are unchanged.
+ */
+export {};

package/dist/types/participant.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Participant identity — a zero-import leaf of the type graph.
+ *
+ * `ParticipantRef` (and the participant-kind literals it carries) is the one
+ * identity shape shared by the streams surface (`types/streams.ts`) and the
+ * conflict-policy layer (`policy/types.ts`). It lives in its own leaf module —
+ * importing nothing — so both layers can depend on it without forming the
+ * foundation triangle `types/streams → schema/model → policy/types →
+ * types/streams`. The runtime validator for the same literals stays in
+ * `coordination/schema.ts` (`participantKindSchema`).
+ */
+/** The participant-kind vocabulary: human session, AI agent, or system actor. */
+export type ParticipantKind = 'user' | 'agent' | 'system';
+/**
+ * Identity reference for an actor / on-behalf-of slot. Generic
+ * protocol vocabulary; works for sessions, agents, and system roles.
+ */
+export interface ParticipantRef {
+    kind: ParticipantKind;
+    id: string;
+}

package/dist/types/participant.js

@@ -0,0 +1,12 @@
+/**
+ * Participant identity — a zero-import leaf of the type graph.
+ *
+ * `ParticipantRef` (and the participant-kind literals it carries) is the one
+ * identity shape shared by the streams surface (`types/streams.ts`) and the
+ * conflict-policy layer (`policy/types.ts`). It lives in its own leaf module —
+ * importing nothing — so both layers can depend on it without forming the
+ * foundation triangle `types/streams → schema/model → policy/types →
+ * types/streams`. The runtime validator for the same literals stays in
+ * `coordination/schema.ts` (`participantKindSchema`).
+ */
+export {};

package/dist/types/streams.d.ts

@@ -19,14 +19,8 @@ export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind,
 export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
-/**
- * Identity reference for an actor / on-behalf-of slot. Generic
- * protocol vocabulary; works for sessions, agents, and system roles.
- */
-export interface ParticipantRef {
-    kind: 'user' | 'agent' | 'system';
-    id: string;
-}
+import type { ParticipantRef } from './participant.js';
+export type { ParticipantRef } from './participant.js';
 /**
  * Whether the human explicitly approved a change. Open-source
  * consumers that don't track approval keep `auto` as the default.
@@ -156,9 +150,9 @@ export interface PresenceStream {
      * agents are doing right now: "copy-bot is generating a new title
      * for slide 5; don't duplicate that work."
      */
-    readonly others: ReadonlyArray<Peer>;
+    readonly others: readonly Peer[];
     /** Subset of `others` filtered to a specific sync group. */
-    othersIn(syncGroup: string): ReadonlyArray<Peer>;
+    othersIn(syncGroup: string): readonly Peer[];
     /**
      * Framework-agnostic reactivity primitive. Register a callback that
      * fires every time `others` / `othersIn(...)` content changes (a
@@ -202,7 +196,7 @@ export interface PresenceStream {
      * down the underlying subscription cleanly via the iterator's
      * `return()` hook.
      */
-    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<Peer>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<readonly Peer[]>;
 }
 /**
  * What a participant is currently doing. This is BOTH the SDK and the
@@ -276,7 +270,7 @@ export interface Peer {
     /** Server timestamp of the most recent frame from this participant. */
     readonly lastActive: string;
     /** Pending-mutation claims this participant has declared. */
-    readonly activeClaims?: ReadonlyArray<Claim>;
+    readonly activeClaims?: readonly Claim[];
 }
 /** Outbound `presence_update` payload. */
 export interface PresenceUpdatePayload {
@@ -341,7 +335,7 @@ export interface ClaimStream {
      * Reads return the current snapshot; pair with `subscribe(...)`
      * below to get notified on change.
      */
-    readonly others: ReadonlyArray<Claim>;
+    readonly others: readonly Claim[];
     /**
      * Reactive view of the wait queue on one target — the FIFO line of
      * `status: 'queued'` claims behind the current holder, each with its
@@ -410,7 +404,7 @@ export interface ClaimStream {
      * }
      * ```
      */
-    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<Claim>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<readonly Claim[]>;
 }
 /**
  * You LOST an claim you were HOLDING — distinct from `ClaimRejection` (a

package/dist/utils/mobx-setup.d.ts

@@ -4,7 +4,7 @@
  * Fixed version that doesn't conflict with existing getters/setters
  */
 import { type AnnotationMapEntry } from 'mobx';
-import { PropertyMetadata, ReferenceMetadata } from '../types/index.js';
+import { type PropertyMetadata, type ReferenceMetadata } from '../types/index.js';
 /**
  * The internal contract M1 relies on. Models invoke M1 from inside
  * their constructor, where these fields are guaranteed to exist on