@abloatai/ablo 0.26.0 → 0.27.0

package/dist/sync/syncCursor.d.ts

@@ -1,44 +1,40 @@
 /**
- * SyncCursor — the sync-position state of one SyncWebSocket session.
+ * 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.
  *
- * Owns the two pieces of resume state the transport carries between
- * connects: the `lastSyncId` watermark and the opaque server cursor.
- * Extracted from SyncWebSocket so cursor bookkeeping is one cohesive
- * leaf instead of fields + accessors spread through the transport
- * class. The advance DISCIPLINE (only move `lastSyncId` on a
- * persistence-gated ack) is documented at the call sites in
- * SyncWebSocket (`sendAck` / `handleDelta`).
- *
- * (The per-entity version vector that used to live here was a Go-era
- * ghost — zero decision reads client- or server-side; one total-ordered
- * log per plane makes the scalar `sync_id` watermark the causality
- * token. Removed in W4a.)
+ * 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);
     /**
-     * Advance the local cursor for an ack — this is what
-     * `requestIncrementalSync` and the connect handshake will send next,
-     * and what `getLastSyncId()` reports for clean-shutdown persistence.
-     * Monotonic: a stale (lower) ack never moves the cursor backward.
+     * 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;
     /**
-     * Update last sync ID (for persistence)
+     * Sets the watermark outright, used when restoring persisted state.
      */
     setLastSyncId(syncId: number): void;
     /**
-     * Update sync cursor (for incremental sync)
+     * Sets the opaque server cursor used for incremental sync.
      */
     setSyncCursor(cursor: string | null): void;
     /**
-     * Get current sync cursor
+     * Returns the current opaque server cursor, or null if none is set.
      */
     getSyncCursor(): string | null;
     /**
-     * Get the highest syncId seen this session (for persistence on clean shutdown)
+     * Returns the highest delta id seen this session, for persistence on a clean
+     * shutdown.
      */
     getLastSyncId(): number;
 }

package/dist/sync/syncCursor.js

@@ -1,18 +1,12 @@
 /**
- * SyncCursor — the sync-position state of one SyncWebSocket session.
+ * 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.
  *
- * Owns the two pieces of resume state the transport carries between
- * connects: the `lastSyncId` watermark and the opaque server cursor.
- * Extracted from SyncWebSocket so cursor bookkeeping is one cohesive
- * leaf instead of fields + accessors spread through the transport
- * class. The advance DISCIPLINE (only move `lastSyncId` on a
- * persistence-gated ack) is documented at the call sites in
- * SyncWebSocket (`sendAck` / `handleDelta`).
- *
- * (The per-entity version vector that used to live here was a Go-era
- * ghost — zero decision reads client- or server-side; one total-ordered
- * log per plane makes the scalar `sync_id` watermark the causality
- * token. Removed in W4a.)
+ * 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;
@@ -22,10 +16,11 @@ export class SyncCursor {
         this.syncCursor = null;
     }
     /**
-     * Advance the local cursor for an ack — this is what
-     * `requestIncrementalSync` and the connect handshake will send next,
-     * and what `getLastSyncId()` reports for clean-shutdown persistence.
-     * Monotonic: a stale (lower) ack never moves the cursor backward.
+     * 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) {
@@ -33,25 +28,26 @@ export class SyncCursor {
         }
     }
     /**
-     * Update last sync ID (for persistence)
+     * Sets the watermark outright, used when restoring persisted state.
      */
     setLastSyncId(syncId) {
         this.lastSyncId = syncId;
     }
     /**
-     * Update sync cursor (for incremental sync)
+     * Sets the opaque server cursor used for incremental sync.
      */
     setSyncCursor(cursor) {
         this.syncCursor = cursor;
     }
     /**
-     * Get current sync cursor
+     * Returns the current opaque server cursor, or null if none is set.
      */
     getSyncCursor() {
         return this.syncCursor;
     }
     /**
-     * Get the highest syncId seen this session (for persistence on clean shutdown)
+     * 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

@@ -1,60 +1,52 @@
 /**
- * syncPlan — schema → sync-plan derivation.
- *
- * Pure leaf extracted from BaseSyncedStore.ts: walks a `Schema` and derives
- * the two declarative arrays the store's constructor consumes (FK indexes,
- * enrichment plan). No class state, no side effects — `BaseSyncedStore`
- * re-exports everything here so importers are unchanged.
+ * 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 ObjectPool at construction time. */
+/** A foreign-key index to register on the in-memory object pool when the store is constructed. */
 export interface ForeignKeyIndexSpec {
     /**
-     * The child model name (where the FK field lives) — this is the type
-     * that will be passed to `pool.registerForeignKey(modelName, fieldName)`
-     * and later to `pool.getByForeignKey(modelName, fieldName, value)`.
-     *
-     * Use the wire `__typename` casing (e.g., `'SlideLayer'`, not
-     * `'slideLayer'`) — that's the value `createFromData` stamps onto
-     * models and the pool indexes by.
+     * 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 FK field name on the child model, e.g. `'slideId'`. */
+    /** The foreign-key field name on the child model, for example `'slideId'`. */
     readonly fieldName: string;
 }
 /**
- * A declarative enrichment rule for the delta-apply path.
- *
- * When a delta for `modelName` arrives, after the model is constructed
- * the base store reads `data[foreignKey]` from the payload, looks up
- * the matching parent in the ObjectPool, and attaches it as
- * `data[relationKey]`. Best-effort: if the parent isn't yet in the
- * pool (e.g., arrived later in the same bootstrap batch), enrichment
- * silently no-ops.
+ * A declarative rule for enriching an incoming row with its related parent.
  *
- * Replaces the previous pattern of overriding `enrichRelations` on a
- * subclass to hardcode per-model enrichment logic.
+ * 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 FK field on the child that points at the parent's id. */
+    /** 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;
 }
 /**
- * Walk a schema and derive the two sync-plan arrays consumed by
- * `BaseSyncedStore`'s constructor: FK indexes to register on the pool,
- * and the enrichment plan.
- *
- * FK indexes and enrichment entries are pulled from each `belongsTo`
- * relation where `options.index` / `options.enrich` is set. Relations
- * without those options are skipped — this is an opt-in mechanism so
- * adding a `belongsTo` never silently changes delta or lookup semantics.
+ * 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}.
  *
- * Pure function: takes a Schema, returns two arrays. No side effects,
- * no class state. Called once at construction time from `BaseSyncedStore`.
+ * 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[];

package/dist/sync/syncPlan.js

@@ -1,23 +1,22 @@
 /**
- * syncPlan — schema → sync-plan derivation.
- *
- * Pure leaf extracted from BaseSyncedStore.ts: walks a `Schema` and derives
- * the two declarative arrays the store's constructor consumes (FK indexes,
- * enrichment plan). No class state, no side effects — `BaseSyncedStore`
- * re-exports everything here so importers are unchanged.
+ * 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}.
  */
 /**
- * Walk a schema and derive the two sync-plan arrays consumed by
- * `BaseSyncedStore`'s constructor: FK indexes to register on the pool,
- * and the enrichment plan.
- *
- * FK indexes and enrichment entries are pulled from each `belongsTo`
- * relation where `options.index` / `options.enrich` is set. Relations
- * without those options are skipped — this is an opt-in mechanism so
- * adding a `belongsTo` never silently changes delta or lookup semantics.
+ * 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}.
  *
- * Pure function: takes a Schema, returns two arrays. No side effects,
- * no class state. Called once at construction time from `BaseSyncedStore`.
+ * 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 = [];
@@ -38,9 +37,9 @@ export function deriveSyncPlanFromSchema(schema) {
                 }
             }
             else if (rel.type === 'hasMany' || rel.type === 'hasOne') {
-                // hasMany/hasOne: the FK lives on the TARGET model, not the current model.
-                // Register the FK index on the target so getByForeignKey works.
-                // Target typename is resolved at registration time from the schema.
+                // 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 });

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;
 }

package/dist/sync/syncPosition.js

@@ -1,61 +1,61 @@
 /**
- * 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 const syncPositionSchema = z.object({
-    /** Resume/ack cursor — advances only after IDB persistence. */
+    /** The resume cursor; advances only after deltas persist to durable local storage. */
     persisted: z.number().int().nonnegative(),
-    /** In-memory cursor — last delta applied to the pool. */
+    /** The in-memory cursor: the last delta applied to the object pool. */
     applied: z.number().int().nonnegative(),
-    /** Highest server watermark acked to this client's own commits. */
+    /** The highest server position acknowledged for this client's own commits. */
     acked: z.number().int().nonnegative(),
 });
 /**
- * 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 function parseSyncPosition(value) {
     const result = syncPositionSchema.safeParse(value);
     return result.success ? result.data : null;
@@ -69,11 +69,13 @@ function advance(state, next) {
         acked: Math.max(state.acked, next.acked ?? 0),
     };
 }
-/** 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 class SyncPosition {
     #state = ZERO;
-    /** Current state — the schema shape, frozen-by-copy. */
+    /** Returns a copy of the current state in the schema's shape. */
     snapshot() {
         return { ...this.#state };
     }
@@ -86,25 +88,28 @@ export class SyncPosition {
     get acked() {
         return this.#state.acked;
     }
-    /** 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() {
         return Math.max(this.#state.applied, this.#state.acked);
     }
-    /** 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) {
         this.#state = advance(this.#state, { persisted: syncId, applied: syncId });
     }
-    /** A delta was APPLIED to the in-memory pool. */
+    /** Records that a delta was applied to the in-memory object pool. */
     advanceApplied(syncId) {
         this.#state = advance(this.#state, { applied: syncId });
     }
-    /** 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) {
         if (lastSyncId !== undefined)
             this.#state = advance(this.#state, { acked: lastSyncId });
     }
-    /** 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) {
         this.#state = advance(this.#state, snapshot);
     }