@abloatai/ablo 0.25.0 → 0.27.0

package/dist/sync/heartbeat.js

@@ -0,0 +1,91 @@
+/**
+ * Application-level heartbeat for the sync WebSocket.
+ *
+ * The browser WebSocket API hides RFC 6455 protocol-level ping and pong frames
+ * from JavaScript, so the server's keepalive cannot be observed by client
+ * code. That leaves the client unable to tell a healthy idle connection apart
+ * from a "zombie" socket whose underlying TCP connection has silently broken
+ * (laptop sleep, NAT timeout, mobile handoff). To close the gap, the client
+ * sends an application-level `{ type: 'ping' }` every 30 seconds and
+ * force-closes the socket if no inbound traffic arrives within 10 seconds. Any
+ * inbound message counts as proof the connection is alive; the explicit `pong`
+ * merely guarantees that something arrives even on an otherwise idle stream.
+ */
+import { getContext } from '../context.js';
+import { PING_INTERVAL_MS } from '../wire/protocol.js';
+/**
+ * The interval between application-level pings, shared with both sides of the
+ * connection: the client pings at the same {@link PING_INTERVAL_MS} the server
+ * uses for its own keepalive, and the claim lease window is derived from the
+ * same constant.
+ */
+export const HEARTBEAT_INTERVAL_MS = PING_INTERVAL_MS;
+export const HEARTBEAT_TIMEOUT_MS = 10_000;
+/**
+ * Runs the application-level heartbeat for one socket. While the socket is
+ * open, it sends a `{ type: 'ping' }` frame every {@link HEARTBEAT_INTERVAL_MS}
+ * and arms a {@link HEARTBEAT_TIMEOUT_MS} watchdog. Any inbound frame clears
+ * the watchdog — the owner calls {@link HeartbeatController.clearHeartbeatTimeout}
+ * from its message handler. If the watchdog fires first, the connection is
+ * treated as a zombie and force-closed, which lets the owner's reconnect path
+ * run.
+ *
+ * The heartbeat exists because the client cannot see the protocol-level
+ * keepalive: browsers answer the server's pings automatically but never expose
+ * those frames to JavaScript. On a half-open connection (laptop wake, NAT
+ * timeout, mobile handoff) the socket can report itself open for minutes
+ * before the operating system surfaces the break, so observable application
+ * traffic is the only reliable signal.
+ */
+export class HeartbeatController {
+    transport;
+    heartbeatTimer = null;
+    heartbeatTimeoutTimer = null;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    start() {
+        this.stop();
+        this.heartbeatTimer = setInterval(() => {
+            if (!this.transport.isSocketOpen())
+                return;
+            // Send the ping. If it throws, the socket is already dead, so
+            // force-close it to let the close event drive the reconnect cycle.
+            try {
+                this.transport.sendPing();
+            }
+            catch (err) {
+                getContext().observability.captureWebSocketError({
+                    context: 'heartbeat-send-failed',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                this.transport.forceClose('heartbeat-send-failed');
+                return;
+            }
+            // Arm the timeout. Any inbound message clears it; an explicit `pong` is
+            // not required, since a delta or any other frame is equally good proof
+            // that the connection is alive.
+            if (this.heartbeatTimeoutTimer)
+                clearTimeout(this.heartbeatTimeoutTimer);
+            this.heartbeatTimeoutTimer = setTimeout(() => {
+                getContext().observability.captureWebSocketError({
+                    context: 'heartbeat-timeout',
+                });
+                this.transport.forceClose('heartbeat-timeout');
+            }, HEARTBEAT_TIMEOUT_MS);
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    stop() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.clearHeartbeatTimeout();
+    }
+    clearHeartbeatTimeout() {
+        if (this.heartbeatTimeoutTimer) {
+            clearTimeout(this.heartbeatTimeoutTimer);
+            this.heartbeatTimeoutTimer = null;
+        }
+    }
+}

package/dist/sync/participants.d.ts

@@ -1,11 +1,11 @@
 import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { Schema, SchemaRecord } from '../schema/schema.js';
+import type { Schema } from '../schema/schema.js';
 import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
 import type { AttachableClaimStream } from './createClaimStream.js';
 /**
- * Scope accepted by participant APIs. The normal SDK shape is an
- * entity target (`{ type, id }`). Raw sync-group strings remain an
- * advanced transport escape hatch.
+ * The scope a participant can be joined to. The usual form is an entity target
+ * (`{ type, id }`); raw sync-group strings are an advanced escape hatch for
+ * addressing a transport scope directly.
  */
 export type ParticipantScope = ClaimTarget | readonly ClaimTarget[] | string | readonly string[] | {
     readonly syncGroup: string;
@@ -19,26 +19,27 @@ export interface EngineParticipant {
 }
 export interface ParticipantJoinOptions {
     /**
-     * Initial focus target: customer schema vocabulary, optionally
-     * narrowed to a path, field, or range. When `scope` is omitted,
-     * this also becomes the routing scope.
+     * The initial focus target, named in your schema's vocabulary and optionally
+     * narrowed to a path, field, or range. When `scope` is omitted, this target
+     * also becomes the routing scope.
      */
     readonly target?: PresenceTarget;
     /** Alias for `target` when the participant is joined to a broader scope. */
     readonly focus?: PresenceTarget;
     /**
-     * Routing scope. Can be one entity, many entities, or a raw
-     * sync-group escape hatch. Use this for "joined to folder, focused
-     * on file" shapes.
+     * The routing scope: one entity, many entities, or a raw sync-group escape
+     * hatch. Use it for "joined to the folder, focused on one file" shapes,
+     * where the participant listens more broadly than its focus target.
      */
     readonly scope?: ParticipantScope;
     /** Present a narrower capability for this logical participant. */
     readonly capabilityToken?: string;
-    /** Claim TTL, in seconds or a compact duration string (`30s`, `5m`). */
+    /** How long the claim lives, in seconds or a compact duration string (`30s`, `5m`). */
     readonly ttlSeconds?: number | string | null;
     /**
-     * Activity to announce immediately after the claim acks. Defaults to
-     * `reading` when `target` is present. Pass false to join silently.
+     * The activity to announce as soon as the claim is acknowledged. Defaults to
+     * `reading` when a `target` is present. Pass `false` to join without
+     * announcing anything.
      */
     readonly activity?: 'reading' | 'viewing' | 'editing' | false;
     readonly detail?: string;
@@ -46,7 +47,7 @@ export interface ParticipantJoinOptions {
 export interface ScopedPresence {
     readonly self: Peer;
     readonly focus: ClaimTarget | null;
-    readonly others: ReadonlyArray<Peer>;
+    readonly others: readonly Peer[];
     update(activity: Activity): void;
     reading(detail?: string): void;
     reading(target: PresenceTarget, detail?: string): void;
@@ -63,17 +64,16 @@ export interface ScopedClaimOptions {
     /** Free-form reason. Defaults to `'editing'`. Common: `'editing'`,
      *  `'writing'`, `'reviewing'`, app-specific phases. */
     readonly reason?: string;
-    /** TTL — server auto-expires the claim after this. */
+    /** How long the claim lives; the server expires it automatically after this. */
     readonly ttl?: import('../types/streams.js').Duration;
 }
 export interface ScopedClaims {
     readonly focus: ClaimTarget | null;
-    readonly others: ReadonlyArray<Claim>;
+    readonly others: readonly Claim[];
     /**
-     * Claim an exclusive claim on the participant's focus target (or
-     * an explicit override via `opts.target`). Single verb — the old
-     * `editing / writing / announce / claim(reason, opts)` overloads
-     * collapsed into this one method.
+     * Takes an exclusive claim on the participant's focus target, or on an
+     * explicit target passed via `opts.target`. While the claim is held, other
+     * participants that request an overlapping target are rejected.
      */
     claim(opts?: ScopedClaimOptions): Claim;
     onRejected(listener: Parameters<ClaimStream['onRejected']>[0]): () => void;
@@ -84,15 +84,15 @@ export interface ParticipantFocusOptions {
     readonly detail?: string;
 }
 export interface JoinedParticipant {
-    /** Current exact thing this participant is reading/editing. */
+    /** The exact entity this participant is currently reading or editing. */
     readonly target: ClaimTarget | null;
     readonly focusTarget: ClaimTarget | null;
-    /** Transport scopes this participant is joined to for visibility/fan-out. */
+    /** The transport scopes this participant is joined to, which govern what it sees and receives. */
     readonly syncGroups: readonly string[];
     readonly presence: ScopedPresence;
     readonly claims: ScopedClaims;
-    readonly peers: ReadonlyArray<Peer>;
-    readonly activeClaims: ReadonlyArray<Claim>;
+    readonly peers: readonly Peer[];
+    readonly activeClaims: readonly Claim[];
     focus(target: PresenceTarget, options?: ParticipantFocusOptions): JoinedParticipant;
     leave(): void;
     [Symbol.asyncDispose](): Promise<void>;
@@ -106,10 +106,10 @@ export interface ParticipantManagerConfig {
     readonly getTransport: () => SyncWebSocket | null;
     readonly presence: PresenceStream;
     readonly claims: AttachableClaimStream;
-    readonly schema?: Schema<SchemaRecord>;
+    readonly schema?: Schema;
 }
 export declare function createParticipantManager(config: ParticipantManagerConfig): ParticipantManager;
-export declare function resolveParticipantSyncGroups(scope: ParticipantScope | undefined, schema?: Schema<SchemaRecord>): string[];
-export declare function syncGroupFromEntityRef(ref: ClaimTarget, schema?: Schema<SchemaRecord>): string;
+export declare function resolveParticipantSyncGroups(scope: ParticipantScope | undefined, schema?: Schema): string[];
+export declare function syncGroupFromEntityRef(ref: ClaimTarget, schema?: Schema): string;
 export declare function parseParticipantTtlSeconds(value: number | string | null | undefined): number | undefined;
 export declare function createParticipantClaimId(): string;

package/dist/sync/schemas.d.ts

@@ -74,7 +74,8 @@ export declare const BootstrapResponseSchema: z.ZodObject<{
 }, z.core.$loose>;
 export type ValidatedBootstrapResponse = z.infer<typeof BootstrapResponseSchema>;
 /**
- * Validate a raw bootstrap response from the server.
- * Logs validation failures via SyncObservability and throws a descriptive error.
+ * Validates a raw bootstrap response from the server and returns the typed
+ * result. On failure it records a diagnostic breadcrumb and throws an
+ * {@link AbloValidationError} describing which fields were invalid.
  */
 export declare function parseBootstrapResponse(raw: unknown): ValidatedBootstrapResponse;

package/dist/sync/schemas.js

@@ -8,7 +8,8 @@ import { z } from 'zod';
 import { getContext } from "../context.js";
 import { AbloValidationError } from "../errors.js";
 // ─── Sync Action Types ───────────────────────────────────────────────────────
-// Mirror of SyncActionType from sync-engine/types.ts
+// The action codes a server delta can carry, matching the wire protocol's
+// action-type set.
 const SYNC_ACTION_VALUES = ['I', 'U', 'D', 'A', 'C', 'G', 'S', 'V'];
 // ─── Server Delta Schema ─────────────────────────────────────────────────────
 export const ServerDeltaSchema = z
@@ -23,11 +24,12 @@ export const ServerDeltaSchema = z
 })
     .passthrough();
 // ─── Model Value Schema ─────────────────────────────────────────────────────
-// Server model values arrive in multiple shapes depending on Go serialization:
-//   - Array: already-parsed JSON array (most common)
-//   - String: double-encoded JSON string from json.RawMessage
-//   - null: from PostgreSQL jsonb_agg with no matching rows
-// This schema normalizes all variants into unknown[] before downstream use.
+// A model's values can arrive in more than one shape depending on how the
+// server serialized them:
+//   - Array: an already-parsed JSON array (the common case)
+//   - String: a JSON array still encoded as a string, which must be parsed
+//   - null: no matching rows
+// This schema normalizes every variant into an array before downstream use.
 const ModelValueSchema = z
     .union([z.array(z.unknown()), z.string(), z.null()])
     .transform((val) => {
@@ -54,15 +56,17 @@ export const BootstrapResponseSchema = z
     deltaCount: z.number().optional(),
     failedModels: z.array(z.string()).optional(),
     timestamp: z.number().default(() => Date.now()),
-    // Server's active schema hash (drift detection). Optional: absent from
-    // older servers / tenants that have never pushed a schema.
+    // The server's active schema hash, used to detect schema drift. Optional:
+    // absent when the server predates this field or the tenant has never
+    // pushed a schema.
     schemaHash: z.string().optional(),
 })
     .passthrough();
 // ─── Parse Helpers ───────────────────────────────────────────────────────────
 /**
- * Validate a raw bootstrap response from the server.
- * Logs validation failures via SyncObservability and throws a descriptive error.
+ * Validates a raw bootstrap response from the server and returns the typed
+ * result. On failure it records a diagnostic breadcrumb and throws an
+ * {@link AbloValidationError} describing which fields were invalid.
  */
 export function parseBootstrapResponse(raw) {
     const result = BootstrapResponseSchema.safeParse(raw);

package/dist/sync/syncCursor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Holds the resume state of one WebSocket sync session: the `lastSyncId`
+ * watermark, which marks the highest delta the client has seen, and an opaque
+ * server cursor used for incremental sync. The transport carries both across
+ * reconnects so the session can resume where it left off.
+ *
+ * The watermark advances under a strict rule — it moves forward only on an
+ * acknowledgement that is gated on durable persistence — which the transport
+ * enforces at its acknowledgement and delta-handling call sites.
+ */
+export declare class SyncCursor {
+    lastSyncId: number;
+    syncCursor: string | null;
+    constructor(lastSyncId: number);
+    /**
+     * Advances the watermark in response to an acknowledgement. This becomes the
+     * value the next incremental-sync request and the connect handshake send, and
+     * the value {@link SyncCursor.getLastSyncId} reports when persisting on a
+     * clean shutdown. The move is monotonic: a stale, lower acknowledgement never
+     * pulls the watermark backward.
+     */
+    ackAdvance(syncId: number): void;
+    /**
+     * Sets the watermark outright, used when restoring persisted state.
+     */
+    setLastSyncId(syncId: number): void;
+    /**
+     * Sets the opaque server cursor used for incremental sync.
+     */
+    setSyncCursor(cursor: string | null): void;
+    /**
+     * Returns the current opaque server cursor, or null if none is set.
+     */
+    getSyncCursor(): string | null;
+    /**
+     * Returns the highest delta id seen this session, for persistence on a clean
+     * shutdown.
+     */
+    getLastSyncId(): number;
+}

package/dist/sync/syncCursor.js

@@ -0,0 +1,55 @@
+/**
+ * Holds the resume state of one WebSocket sync session: the `lastSyncId`
+ * watermark, which marks the highest delta the client has seen, and an opaque
+ * server cursor used for incremental sync. The transport carries both across
+ * reconnects so the session can resume where it left off.
+ *
+ * The watermark advances under a strict rule — it moves forward only on an
+ * acknowledgement that is gated on durable persistence — which the transport
+ * enforces at its acknowledgement and delta-handling call sites.
+ */
+export class SyncCursor {
+    lastSyncId;
+    syncCursor;
+    constructor(lastSyncId) {
+        this.lastSyncId = lastSyncId;
+        this.syncCursor = null;
+    }
+    /**
+     * Advances the watermark in response to an acknowledgement. This becomes the
+     * value the next incremental-sync request and the connect handshake send, and
+     * the value {@link SyncCursor.getLastSyncId} reports when persisting on a
+     * clean shutdown. The move is monotonic: a stale, lower acknowledgement never
+     * pulls the watermark backward.
+     */
+    ackAdvance(syncId) {
+        if (syncId > this.lastSyncId) {
+            this.lastSyncId = syncId;
+        }
+    }
+    /**
+     * Sets the watermark outright, used when restoring persisted state.
+     */
+    setLastSyncId(syncId) {
+        this.lastSyncId = syncId;
+    }
+    /**
+     * Sets the opaque server cursor used for incremental sync.
+     */
+    setSyncCursor(cursor) {
+        this.syncCursor = cursor;
+    }
+    /**
+     * Returns the current opaque server cursor, or null if none is set.
+     */
+    getSyncCursor() {
+        return this.syncCursor;
+    }
+    /**
+     * Returns the highest delta id seen this session, for persistence on a clean
+     * shutdown.
+     */
+    getLastSyncId() {
+        return this.lastSyncId || 0;
+    }
+}

package/dist/sync/syncPlan.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Derives a client's sync plan from its {@link Schema}. Walking the schema's
+ * models and relations, it produces two declarative arrays consumed when the
+ * store is constructed: the foreign-key indexes to register on the in-memory
+ * object pool, and the enrichment rules that attach related parents to
+ * incoming rows. See {@link deriveSyncPlanFromSchema}.
+ */
+import type { Schema } from '../schema/schema.js';
+/** A foreign-key index to register on the in-memory object pool when the store is constructed. */
+export interface ForeignKeyIndexSpec {
+    /**
+     * The name of the child model, where the foreign-key field lives, and the
+     * name the object pool indexes by. Use the wire type-name casing (for
+     * example `'SlideLayer'`, not `'slideLayer'`), since that is the value
+     * stamped onto reconstructed models and the key the pool looks up.
+     */
+    readonly modelName: string;
+    /** The foreign-key field name on the child model, for example `'slideId'`. */
+    readonly fieldName: string;
+}
+/**
+ * A declarative rule for enriching an incoming row with its related parent.
+ *
+ * When a delta for `modelName` arrives and its row has been constructed, the
+ * store reads the row's `foreignKey` value, looks up the matching parent in
+ * the object pool, and attaches it under `relationKey`. Enrichment is
+ * best-effort: if the parent is not in the pool yet — for example, it arrives
+ * later in the same bootstrap batch — the step is skipped without error.
+ */
+export interface EnrichmentPlanEntry {
+    /** The child model whose incoming deltas should be enriched. */
+    readonly modelName: string;
+    /** The foreign-key field on the child that points at the parent's id. */
+    readonly foreignKey: string;
+    /** The property name under which to attach the parent model. */
+    readonly relationKey: string;
+}
+/**
+ * Walks a schema and derives the two sync-plan arrays used when the store is
+ * constructed: the foreign-key indexes to register on the object pool and the
+ * enrichment plan. See {@link ForeignKeyIndexSpec} and
+ * {@link EnrichmentPlanEntry}.
+ *
+ * Both are drawn from each `belongsTo` relation that sets `options.index` or
+ * `options.enrich`; relations without those options are skipped. Enabling them
+ * is opt-in, so adding a `belongsTo` relation never silently changes how deltas
+ * apply or how lookups resolve. A `hasMany` or `hasOne` relation registers its
+ * index on the target model, since that is where the foreign key lives. The
+ * function has no side effects and is called once at construction.
+ */
+export declare function deriveSyncPlanFromSchema(schema: Schema): {
+    enrichmentPlan: EnrichmentPlanEntry[];
+    foreignKeyIndexes: ForeignKeyIndexSpec[];
+};

package/dist/sync/syncPlan.js

@@ -0,0 +1,50 @@
+/**
+ * Derives a client's sync plan from its {@link Schema}. Walking the schema's
+ * models and relations, it produces two declarative arrays consumed when the
+ * store is constructed: the foreign-key indexes to register on the in-memory
+ * object pool, and the enrichment rules that attach related parents to
+ * incoming rows. See {@link deriveSyncPlanFromSchema}.
+ */
+/**
+ * Walks a schema and derives the two sync-plan arrays used when the store is
+ * constructed: the foreign-key indexes to register on the object pool and the
+ * enrichment plan. See {@link ForeignKeyIndexSpec} and
+ * {@link EnrichmentPlanEntry}.
+ *
+ * Both are drawn from each `belongsTo` relation that sets `options.index` or
+ * `options.enrich`; relations without those options are skipped. Enabling them
+ * is opt-in, so adding a `belongsTo` relation never silently changes how deltas
+ * apply or how lookups resolve. A `hasMany` or `hasOne` relation registers its
+ * index on the target model, since that is where the foreign key lives. The
+ * function has no side effects and is called once at construction.
+ */
+export function deriveSyncPlanFromSchema(schema) {
+    const enrichmentPlan = [];
+    const foreignKeyIndexes = [];
+    for (const [modelName, def] of Object.entries(schema.models)) {
+        const typename = def.typename ?? modelName;
+        for (const [relationKey, rel] of Object.entries(def.relations)) {
+            if (rel.type === 'belongsTo') {
+                if (rel.options?.index) {
+                    foreignKeyIndexes.push({ modelName: typename, fieldName: rel.foreignKey });
+                }
+                if (rel.options?.enrich) {
+                    enrichmentPlan.push({
+                        modelName: typename,
+                        foreignKey: rel.foreignKey,
+                        relationKey,
+                    });
+                }
+            }
+            else if (rel.type === 'hasMany' || rel.type === 'hasOne') {
+                // For hasMany and hasOne, the foreign key lives on the target model,
+                // not the current one, so register the index on the target. Its wire
+                // type name is resolved from the schema here.
+                const targetDef = schema.models[rel.target];
+                const targetTypename = targetDef?.typename ?? rel.target;
+                foreignKeyIndexes.push({ modelName: targetTypename, fieldName: rel.foreignKey });
+            }
+        }
+    }
+    return { enrichmentPlan, foreignKeyIndexes };
+}

package/dist/sync/syncPosition.d.ts

@@ -1,40 +1,39 @@
 /**
- * THE sync-position structure — one typed object for "where is this client
- * in the global delta order", replacing five scattered private counters
- * (`lastSeenSyncId` on the queue, `highestProcessedSyncId` + `lastAckedId`
- * on the store, ad-hoc acked watermarks, `max()` calls at snapshot sites).
+ * Records where this client stands in the global delta order. It is a single
+ * typed object holding three related but distinct positions, each with its own
+ * rule for when it may advance. Keeping them separate is deliberate: collapsing
+ * them into one counter is a classic source of sync bugs.
  *
- * Three facts with DIFFERENT advance disciplines — flattening them was the
- * historical bug source, so the structure models them explicitly:
+ *   - `persisted` — the resume cursor. It advances only after deltas have
+ *     committed to durable local storage. This is the value reconnect catch-up
+ *     sends to the server, so it must never run ahead of what actually landed
+ *     on disk; otherwise the server would skip deltas the client never stored.
  *
- *   - `persisted` — the resume/ack cursor. Advances ONLY after deltas have
- *     committed to IndexedDB (the Replicache "lastMutationID read in the
- *     same transaction as the client view" rule — see SyncWebSocket.sendAck).
- *     This is what reconnect catch-up sends; it must never run ahead of
- *     durable state or the server skips deltas that never landed.
+ *   - `applied` — the in-memory cursor: the last delta applied to the object
+ *     pool. It drives the guards that deduplicate and reject replayed deltas.
+ *     It may run ahead of `persisted`, because the pool is updated before the
+ *     flush to disk, and behind what has merely been received, because
+ *     bootstrap-queued deltas arrive before they are applied.
  *
- *   - `applied` — the in-memory cursor: the last delta APPLIED to the
- *     object pool. Drives delta dedup/replay guards. May run ahead of
- *     `persisted` (pool applies before the IDB flush) and behind receipt
- *     (bootstrap-queued deltas are received but not yet applied).
+ *   - `acked` — the highest server position acknowledged for this client's own
+ *     commits. An acknowledgement at N means the server applied our write at N;
+ *     the optimistic pool already reflects it, so for the entities we wrote we
+ *     have effectively read through N even before the echo returns on the
+ *     stream.
  *
- *   - `acked` — the highest server watermark ACKED to this client's OWN
- *     commits. An ack at N means the server applied our write at N; the
- *     optimistic pool already reflects it, so for entities we wrote we have
- *     logically read through N even before the stream echo arrives.
+ * One value is derived: `readFloor` is the greater of `applied` and `acked`,
+ * and is the only position a snapshot or claim should stamp as its read point.
+ * Using the raw stream cursor alone would make a claim taken right after a
+ * confirmed write look stale against that write's own delta; using the raw
+ * acknowledgement alone would be wrong for read-only clients. The maximum is
+ * correct per entity, because a competing change to an entity we just wrote
+ * necessarily lands above our acknowledgement and still rejects as stale.
  *
- * One derived read: `readFloor` = max(applied, acked) — the ONLY value
- * snapshots/claims may stamp as `readAt`. The bare stream cursor made a
- * claim taken right after an ack-confirmed write stale against that write's
- * own delta; the bare ack would be wrong for read-only clients. Per-entity
- * correct: a foreign change to an entity we just wrote necessarily lands
- * ABOVE our ack and still stale-rejects.
- *
- * The Zod schema IS the state shape — the class holds exactly one
- * `SyncPositionSnapshot` and applies monotonic merges to it, so
- * snapshot/restore are identity-shaped and the schema is the single gate
- * for anything loaded from disk (`parseSyncPosition`; a corrupted stored
- * cursor "ahead of reality" is an existing, known failure mode).
+ * The validation schema is the state shape: the class holds exactly one
+ * {@link SyncPositionSnapshot} and merges monotonically into it, so snapshot
+ * and restore share that shape and {@link parseSyncPosition} is the single gate
+ * for anything loaded from disk — a corrupted cursor stored "ahead of reality"
+ * being a known failure mode.
  */
 import { z } from 'zod';
 export declare const syncPositionSchema: z.ZodObject<{
@@ -44,35 +43,41 @@ export declare const syncPositionSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type SyncPositionSnapshot = z.infer<typeof syncPositionSchema>;
 /**
- * PERSISTENCE DESIGN: only the `persisted` cursor is stored durably (as
- * `WorkspaceMetadata.lastSyncId`, written by Database after each IDB delta
- * commit and gated on load through `syncPositionSchema.shape.persisted` in
- * `Database.requiredBootstrap`). Persisting `applied`/`acked` would be
- * meaningless: on resume the pool is rebuilt FROM the persisted state, so
- * the correct restore is exactly `advancePersisted(storedCursor)` — which
- * implies `applied`, while `acked` starts at 0 (a dead session's acks carry
- * no read authority; the offline queue re-acks its own replays).
+ * Only the `persisted` cursor is stored durably; `applied` and `acked` are
+ * not. On resume the object pool is rebuilt from the persisted state, so the
+ * correct restore is simply to advance `persisted` to the stored value, which
+ * also implies `applied`. `acked` starts at zero, because a past session's
+ * acknowledgements carry no read authority and the offline queue
+ * re-acknowledges its own replays.
+ */
+/**
+ * Validates an untrusted value, such as one loaded from disk, into a position
+ * snapshot, or returns null when it does not match the schema.
  */
-/** Validate a persisted/foreign value into a position snapshot. */
 export declare function parseSyncPosition(value: unknown): SyncPositionSnapshot | null;
-/** The live position. One instance per client (owned by SyncClient); the
- *  three producers advance their own fact, consumers read. */
+/**
+ * The live sync position: one instance per client. Three producers each
+ * advance their own cursor, and consumers read the result.
+ */
 export declare class SyncPosition {
     #private;
-    /** Current state — the schema shape, frozen-by-copy. */
+    /** Returns a copy of the current state in the schema's shape. */
     snapshot(): SyncPositionSnapshot;
     get persisted(): number;
     get applied(): number;
     get acked(): number;
-    /** THE value snapshots/claims stamp as `readAt`. */
+    /** The position a snapshot or claim stamps as its read point: the greater of `applied` and `acked`. */
     get readFloor(): number;
-    /** Deltas through `syncId` have COMMITTED to IndexedDB. Persisting
-     *  implies applied — the flush path applies before/with persisting. */
+    /**
+     * Records that deltas through `syncId` have committed to durable local
+     * storage. This also advances `applied`, since the flush applies each delta
+     * before or as it persists.
+     */
     advancePersisted(syncId: number): void;
-    /** A delta was APPLIED to the in-memory pool. */
+    /** Records that a delta was applied to the in-memory object pool. */
     advanceApplied(syncId: number): void;
-    /** The server acked one of OUR commits at this watermark. */
+    /** Records that the server acknowledged one of this client's commits at the given position. */
     noteAck(lastSyncId: number | undefined): void;
-    /** Restore from a VALIDATED snapshot (e.g. IDB resume). Monotonic. */
+    /** Restores from an already-validated snapshot, for example on resume from disk. The merge is monotonic. */
     restore(snapshot: SyncPositionSnapshot): void;
 }