@abloatai/ablo 0.26.0 → 0.27.0

package/dist/sync/awaitClaimGrant.d.ts

@@ -1,30 +1,30 @@
 /**
- * `awaitClaimGrant` — the client side of the fair-queue handover.
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
  *
- * When a `claim` is contended, the server enqueues it and replies `queued`
- * (HTTP 202 on `/v1/claims`, or `claim_queued` over WS). The grant is then
- * PUSHED later over the WS as `claim_granted` when the claim reaches the head.
- * This resolves once that frame arrives for our `claimId` — so the caller's
- * `claim` promise stays pending (event-driven; no poll, no race) until it's
- * actually our turn. Rejects on `claim_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
- * lapse on disconnect, revoke) or an optional timeout.
- *
- * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
- * fake; `SyncWebSocket` satisfies it structurally.
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; {@link SyncWebSocket} satisfies it.
  */
 export interface GrantTransport {
     subscribe(event: 'claim_acquired' | 'claim_granted' | 'claim_lost' | 'claim_queued' | 'claim_rejected', handler: (payload: Record<string, unknown>) => void): () => void;
 }
 export interface ClaimGrantInfo {
     /**
-     * True when the grant arrived as `claim_granted` — i.e. the target was
-     * HELD when we asked and we waited in the FIFO line behind the holder.
-     * False for the immediate `claim_acquired` (target was free).
+     * True when the grant arrived as `claim_granted` — the target was held when
+     * the caller asked, and the caller waited in the FIFO line behind the holder.
+     * False for the immediate `claim_acquired`, where the target was free.
      *
-     * Callers use this to know the row may have changed while we queued:
-     * claim VISIBILITY is entity-scoped (org-wide subscriptions receive no
-     * presence/claim fan-out — see Hub.broadcastPresenceChange), so the
-     * local coordination snapshot cannot be trusted to detect "we waited".
+     * Callers read this to know the row may have changed while they queued. Claim
+     * visibility is scoped to the entity, so a broad, organization-wide
+     * subscription receives no presence or claim fan-out, and the local
+     * coordination snapshot cannot be trusted to tell whether the caller waited.
      * The grant frame itself is the authoritative signal.
      */
     readonly waited: boolean;

package/dist/sync/awaitClaimGrant.js

@@ -1,16 +1,16 @@
 /**
- * `awaitClaimGrant` — the client side of the fair-queue handover.
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
  *
- * When a `claim` is contended, the server enqueues it and replies `queued`
- * (HTTP 202 on `/v1/claims`, or `claim_queued` over WS). The grant is then
- * PUSHED later over the WS as `claim_granted` when the claim reaches the head.
- * This resolves once that frame arrives for our `claimId` — so the caller's
- * `claim` promise stays pending (event-driven; no poll, no race) until it's
- * actually our turn. Rejects on `claim_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
- * lapse on disconnect, revoke) or an optional timeout.
- *
- * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
- * fake; `SyncWebSocket` satisfies it structurally.
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; {@link SyncWebSocket} satisfies it.
  */
 import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
 import { getContext } from '../context.js';

package/dist/sync/bootstrapApply.d.ts

@@ -1,18 +1,22 @@
 /**
- * bootstrapApply — applying bootstrap results to the in-memory pool.
+ * Applies a bootstrap result to the in-memory object pool. When a client
+ * connects, the server sends either a full snapshot of the models it can see or
+ * a partial catch-up of the deltas it missed. These functions route that result
+ * into the pool, protect entities that arrived mid-bootstrap from being swept
+ * away as stale, and replay any deltas that queued while the bootstrap was in
+ * flight.
  *
- * Extracted from BaseSyncedStore.ts as a cohesive leaf: routing a
- * full/partial bootstrap result through the pool-write facade, collecting
- * the delta-protected ids that must survive ghost removal, and replaying
- * the deltas queued during an active bootstrap. The store keeps thin
- * protected delegates with unchanged signatures and talks back through the
- * minimal {@link PoolContext} — never the store's class type — so no
- * module cycle forms. The heavy lifting (model creation, healing, upsert,
- * ghost removal) stays owned by `SyncClient`.
+ * The functions here reach their host store only through the small
+ * {@link PoolContext} interface, not the store's concrete class, so the two can
+ * reference each other without forming an import cycle. The pool writes
+ * themselves — creating models, healing partial rows, upserting, and removing
+ * stale local copies the server no longer reports — are performed by the sync
+ * client behind that interface.
  */
 import type { BootstrapResult } from '../Database.js';
 import type { SyncDelta } from './SyncWebSocket.js';
-/** Rehydration statistics from bootstrap */
+/** Counts describing what applying a bootstrap changed in the pool: entities
+ *  added, updated, removed, skipped, and healed, plus the elapsed time. */
 export interface RehydrationStats {
     added: number;
     updated: number;
@@ -22,14 +26,15 @@ export interface RehydrationStats {
     elapsedMs: number;
 }
 /**
- * What the bootstrap-apply path needs back from its host store. The two
- * `SyncClient` facades come with enrichment pre-bound by the host, so the
- * store's `enrichRelations` override point keeps its dynamic dispatch.
+ * The methods the bootstrap-apply functions call back into on the host store.
+ * The two data-application methods arrive with relation enrichment already
+ * bound by the host, so a subclass override of how relations are enriched still
+ * takes effect through this interface.
  */
 export interface PoolContext {
-    /** `SyncClient.applyDeltaBatchToPool` with the host's `enrichRelations` bound. */
+    /** Applies persisted delta results to the in-memory pool, with the host's relation enrichment bound. */
     applyDeltaBatchToPool(results: NonNullable<BootstrapResult['deltaResults']>): void;
-    /** `SyncClient.applyBootstrapDataToPool` — model creation, healing, pool upsert, ghost removal. */
+    /** Writes bootstrap data into the pool: creates models, heals partial rows, upserts, and removes stale local copies the server no longer reports. */
     applyBootstrapDataToPool(bootstrapData: {
         models?: Record<string, unknown[]>;
         failedModels?: string[];
@@ -42,19 +47,24 @@ export interface PoolContext {
     };
     /** Pool size — for the completion log line. */
     getPoolSize(): number;
-    /** Every id currently in the pool — for delta-protected-id collection. */
+    /** Every id currently in the pool, used to work out which entities must survive the stale-sweep (see {@link collectDeltaProtectedIds}). */
     getAllPoolIds(): string[];
-    /** Deltas queued during an active bootstrap; null when none is in flight.
-     *  Backed by the host's `bootstrapDeltaQueue` field (get/set accessors). */
+    /** Deltas that queued while a bootstrap was in flight; null when no bootstrap
+     *  is running. The host backs this with a field exposed through accessors. */
     bootstrapDeltaQueue: SyncDelta[] | null;
-    /** The host's atomic frame apply — `applyDeltaFrame` deliberately stays
-     *  in BaseSyncedStore (the authoritative-apply correctness seam). */
+    /** Applies a complete set of deltas to the pool atomically — one write, one
+     *  re-render. This entry point lives on the host, not in this module. */
     applyDeltaFrame(deltas: SyncDelta[]): void;
 }
-/** Apply bootstrap data to the ObjectPool with ghost removal */
-/** Apply bootstrap data to the ObjectPool. Delegates pool writes to SyncClient. */
+/**
+ * Applies a bootstrap result to the in-memory pool and returns what changed.
+ * A full bootstrap creates, heals, and upserts models and removes stale local
+ * copies the server no longer reports; a partial bootstrap routes the missed
+ * deltas through the delta-apply path so deletions evict their entities. See
+ * {@link RehydrationStats} for the returned counts.
+ */
 export declare function applyBootstrapToPool(ctx: PoolContext, bootstrapResult: BootstrapResult, protectedIds?: ReadonlySet<string>): RehydrationStats;
-/** Collect IDs that must survive ghost removal (added by deltas during bootstrap) */
+/** Collects the ids that must survive the post-bootstrap stale-sweep: entities added by deltas that arrived while the bootstrap was in flight. */
 export declare function collectDeltaProtectedIds(ctx: PoolContext, preBootstrapIds: ReadonlySet<string>): Set<string>;
-/** Replay deltas queued during bootstrap */
+/** Replays the deltas that queued while a bootstrap was in flight, applying them as one atomic frame. */
 export declare function replayQueuedDeltas(ctx: PoolContext): void;

package/dist/sync/bootstrapApply.js

@@ -1,25 +1,33 @@
 /**
- * bootstrapApply — applying bootstrap results to the in-memory pool.
+ * Applies a bootstrap result to the in-memory object pool. When a client
+ * connects, the server sends either a full snapshot of the models it can see or
+ * a partial catch-up of the deltas it missed. These functions route that result
+ * into the pool, protect entities that arrived mid-bootstrap from being swept
+ * away as stale, and replay any deltas that queued while the bootstrap was in
+ * flight.
  *
- * Extracted from BaseSyncedStore.ts as a cohesive leaf: routing a
- * full/partial bootstrap result through the pool-write facade, collecting
- * the delta-protected ids that must survive ghost removal, and replaying
- * the deltas queued during an active bootstrap. The store keeps thin
- * protected delegates with unchanged signatures and talks back through the
- * minimal {@link PoolContext} — never the store's class type — so no
- * module cycle forms. The heavy lifting (model creation, healing, upsert,
- * ghost removal) stays owned by `SyncClient`.
+ * The functions here reach their host store only through the small
+ * {@link PoolContext} interface, not the store's concrete class, so the two can
+ * reference each other without forming an import cycle. The pool writes
+ * themselves — creating models, healing partial rows, upserting, and removing
+ * stale local copies the server no longer reports — are performed by the sync
+ * client behind that interface.
  */
 import { getContext } from '../context.js';
-/** Apply bootstrap data to the ObjectPool with ghost removal */
-/** Apply bootstrap data to the ObjectPool. Delegates pool writes to SyncClient. */
+/**
+ * Applies a bootstrap result to the in-memory pool and returns what changed.
+ * A full bootstrap creates, heals, and upserts models and removes stale local
+ * copies the server no longer reports; a partial bootstrap routes the missed
+ * deltas through the delta-apply path so deletions evict their entities. See
+ * {@link RehydrationStats} for the returned counts.
+ */
 export function applyBootstrapToPool(ctx, bootstrapResult, protectedIds) {
     const { bootstrapData } = bootstrapResult;
-    // Partial bootstrap: Database.processDeltaBatch already wrote the deltas
-    // to IDB. Route the same results through the delta-apply path so the
-    // in-memory pool evicts deleted entities (and updates modified ones).
-    // Without this, reconnect DELETEs persist to IDB but the canvas keeps
-    // showing ghost layers until a full reload.
+    // Partial bootstrap: the missed deltas are already written to the local
+    // store. Route the same results through the delta-apply path so the
+    // in-memory pool also evicts deleted entities and updates modified ones.
+    // Without this, a reconnect delete persists locally but its stale copy
+    // lingers in the pool until a full reload.
     if (bootstrapData.type === 'partial') {
         const deltaResults = bootstrapResult.deltaResults;
         if (deltaResults && deltaResults.length > 0) {
@@ -31,7 +39,7 @@ export function applyBootstrapToPool(ctx, bootstrapResult, protectedIds) {
         return { added: 0, updated: 0, removed: 0, skipped: 0, healed: 0, elapsedMs: 0 };
     }
     const start = typeof performance !== 'undefined' ? performance.now() : Date.now();
-    // SyncClient owns: model creation, healing, pool upsert, ghost removal
+    // Creates models, heals partial rows, upserts, and removes stale local copies.
     const stats = ctx.applyBootstrapDataToPool(bootstrapData, protectedIds);
     const elapsedMs = Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - start);
     getContext().logger.info('[BaseSyncedStore] Bootstrap applied', {
@@ -39,7 +47,7 @@ export function applyBootstrapToPool(ctx, bootstrapResult, protectedIds) {
     });
     return { ...stats, elapsedMs };
 }
-/** Collect IDs that must survive ghost removal (added by deltas during bootstrap) */
+/** Collects the ids that must survive the post-bootstrap stale-sweep: entities added by deltas that arrived while the bootstrap was in flight. */
 export function collectDeltaProtectedIds(ctx, preBootstrapIds) {
     const protectedIds = new Set();
     for (const id of ctx.getAllPoolIds()) {
@@ -52,7 +60,7 @@ export function collectDeltaProtectedIds(ctx, preBootstrapIds) {
     }
     return protectedIds;
 }
-/** Replay deltas queued during bootstrap */
+/** Replays the deltas that queued while a bootstrap was in flight, applying them as one atomic frame. */
 export function replayQueuedDeltas(ctx) {
     const queue = ctx.bootstrapDeltaQueue;
     ctx.bootstrapDeltaQueue = null;

package/dist/sync/commitFrames.d.ts

@@ -1,29 +1,30 @@
 /**
- * Commit-path frame builders and claim instrumentation for the sync
- * WebSocket — pure functions with no socket state, extracted from
- * SyncWebSocket so the wire codec is a leaf the transport (and the frame
- * dispatch table) can share.
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
  */
 import type { CommitMessage } from '../wire/index.js';
 import type { MutationOperation, ClaimEvent } from '../interfaces/index.js';
 import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 /**
- * Resolution value of a commit ack. `notifications` is present only when a
- * guarded write (`onStale: 'notify') hit a concurrent change — the
- * advisory self-heal signal, surfaced both here and via `conflict:notified`.
+ * The value a commit acknowledgement resolves to. `notifications` is present
+ * only when a guarded write (`onStale: 'notify'`) met a concurrent change; it
+ * carries the advisory signal that lets the writer self-heal, and the same
+ * signal also arrives on the `conflict:notified` event.
  */
 export interface CommitAck {
     lastSyncId: number;
     notifications?: StaleNotification[];
 }
 /**
- * Project the SDK's `MutationOperation[]` onto the canonical wire
- * `CommitMessage`. This is the single serialize boundary between the SDK op
- * type (loose `type: string`, plus an SDK-internal `options` the server never
- * reads) and the strict wire contract. The per-field map gives compile-time
- * drift detection (a `CommitOperation` shape change breaks here) and the lone
- * `as` narrows the validated op `type` to the wire union — the only
- * loosening, localized to this boundary.
+ * Converts the client's list of {@link MutationOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link CommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
  */
 export declare function buildCommitFrame(operations: readonly MutationOperation[], clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): CommitMessage;
 /**
@@ -33,11 +34,11 @@ export declare function buildCommitFrame(operations: readonly MutationOperation[
  */
 export declare function parseNotifications(raw: unknown): StaleNotification[] | undefined;
 /**
- * Single instrumentation point for claim events. Every `claim_*` frame routes
- * through here so a developer debugging a collision gets one consistent trace
- * — a console line AND a structured capture — without each dispatch case
- * re-deriving the row/holder shape. The wire payload is loosely typed
- * (`Record<string, unknown>`), so this is the one place that narrows it into
- * a {@link ClaimEvent}.
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape. The wire payload is loosely typed
+ * (`Record<string, unknown>`), so this is the one place that narrows it into a
+ * {@link ClaimEvent}.
  */
 export declare function recordClaim(phase: ClaimEvent['phase'], payload: Record<string, unknown>): void;

package/dist/sync/commitFrames.js

@@ -1,20 +1,20 @@
 /**
- * Commit-path frame builders and claim instrumentation for the sync
- * WebSocket — pure functions with no socket state, extracted from
- * SyncWebSocket so the wire codec is a leaf the transport (and the frame
- * dispatch table) can share.
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
  */
 import { getContext } from '../context.js';
 import { staleNotificationSchema, wireParticipantKindSchema, } from '../coordination/schema.js';
 import { formatClaim } from '../coordination/trace.js';
 /**
- * Project the SDK's `MutationOperation[]` onto the canonical wire
- * `CommitMessage`. This is the single serialize boundary between the SDK op
- * type (loose `type: string`, plus an SDK-internal `options` the server never
- * reads) and the strict wire contract. The per-field map gives compile-time
- * drift detection (a `CommitOperation` shape change breaks here) and the lone
- * `as` narrows the validated op `type` to the wire union — the only
- * loosening, localized to this boundary.
+ * Converts the client's list of {@link MutationOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link CommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
  */
 export function buildCommitFrame(operations, clientTxId, causedByTaskId, reads) {
     const payload = {
@@ -31,7 +31,7 @@ export function buildCommitFrame(operations, clientTxId, causedByTaskId, reads)
     };
     if (causedByTaskId)
         payload.causedByTaskId = causedByTaskId;
-    // Batch-level read-set (STORM layer): rows/groups the batch was premised on.
+    // The read set the batch was premised on: the rows or groups the writer read before committing.
     if (reads && reads.length > 0)
         payload.reads = [...reads];
     return { type: 'commit', payload };
@@ -53,12 +53,12 @@ export function parseNotifications(raw) {
     return out.length > 0 ? out : undefined;
 }
 /**
- * Single instrumentation point for claim events. Every `claim_*` frame routes
- * through here so a developer debugging a collision gets one consistent trace
- * — a console line AND a structured capture — without each dispatch case
- * re-deriving the row/holder shape. The wire payload is loosely typed
- * (`Record<string, unknown>`), so this is the one place that narrows it into
- * a {@link ClaimEvent}.
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape. The wire payload is loosely typed
+ * (`Record<string, unknown>`), so this is the one place that narrows it into a
+ * {@link ClaimEvent}.
  */
 export function recordClaim(phase, payload) {
     const str = (v) => typeof v === 'string' ? v : undefined;

package/dist/sync/createClaimStream.d.ts

@@ -1,25 +1,25 @@
 /**
- * Transport-driven ClaimStream factory.
+ * Creates a {@link ClaimStream} over a live sync connection. A claim is a
+ * short-lived, advisory lease a participant takes on an entity (or a field of
+ * one) to signal "I'm working on this"; the stream lets you take claims, see
+ * everyone else's, and watch the wait queue when a claim is contended.
  *
- * Mirrors `createPresenceStream` — built directly on `SyncWebSocket`,
- * no SyncAgent wrapper. Claims derive their `others` view from the
- * same `presence_update` frames the presence stream consumes (the
- * Hub piggybacks `activeClaims` on every presence frame). Outbound
- * announce/revoke ride the same socket via `claim_begin` /
+ * The stream is built directly on the sync WebSocket and shares that one
+ * connection. It learns about other participants' claims from the same
+ * `presence_update` frames the {@link createPresenceStream} presence stream
+ * consumes — the server piggybacks each participant's `activeClaims` on every
+ * presence frame — and sends its own claims as `claim_begin` and
  * `claim_abandon` frames.
  *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
- *       entityType, entityId, reason, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
- *       entityType?, entityId? } }`
- *   • Inbound (via presence): `event.activeClaims: Claim[]`
- *     stamped with `declaredAt`, `expiresAt`.
- *   • Inbound: `claim_rejected` event with conflict metadata.
- *
- * After the dual-engine collapse (step #36), this is the only
- * ClaimStream factory in the SDK; the older compatibility path
- * deletes.
+ * Wire frames:
+ *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
+ *       entityId, reason, field?, estimatedMs? }`.
+ *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
+ *       entityId? }`.
+ *   • Inbound, via presence — `event.activeClaims`, each stamped with
+ *       `declaredAt` and `expiresAt`.
+ *   • Inbound `claim_rejected` — the server refused the claim, with conflict
+ *       metadata.
  */
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '../types/streams.js';
@@ -29,10 +29,11 @@ export interface ClaimStreamConfig {
 }
 export interface AttachableClaimStream extends ClaimStream {
     /**
-     * INTERNAL lease mint — sends the `claim_begin` frame and returns a held
-     * {@link Claim} (no row `data`; the model door reads the row and stamps it).
-     * Not part of the public `ClaimStream` surface: the only public way to take a
-     * claim is `ablo.<model>.claim({ id })`, which builds on this.
+     * Mints a lease directly: sends the `claim_begin` frame and returns a held
+     * {@link Claim} that carries no row `data` (the resource layer reads the row
+     * and stamps it). This is an internal entry point, not part of the public
+     * {@link ClaimStream}; application code takes a claim through
+     * `ablo.<model>.claim({ id })`, which is built on this.
      */
     claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
     attach(transport: SyncWebSocket): void;