@abloatai/ablo 0.26.0 → 0.27.0

package/dist/coordination/schema.js

@@ -1,23 +1,20 @@
 import { z } from 'zod';
 import { syncGroupInputSchema } from '../schema/roles.js';
 /**
- * Coordination wire schema — the ONE canonical source for the three layers
- * that keep humans and agents from clobbering each other on a shared row.
- * See `packages/sync-engine/docs/coordination.md` ("The model — three layers,
- * one decision") for the conceptual model. The layers, outer-to-inner:
+ * The wire schemas for coordination — the shapes that keep humans and agents
+ * from overwriting each other on a shared row. Coordination works in three
+ * layers, from outermost to innermost:
  *
- *   1. PRESENCE       (observation)    — who is working where; NEVER enforces.
- *   2. PESSIMISTIC    (claims/leases)  — `claim_begin`/`claim_abandon`;
- *                                        mutual exclusion between participants.
- *   3. OPTIMISTIC     (stale-context)  — `readAt` + `onStale` write-guard;
- *                                        last-writer-wins lost-update detection.
+ *   1. Presence (observation): who is working where. It reports, never blocks.
+ *   2. Claims (pessimistic leases): `claim_begin` / `claim_abandon` grant one
+ *      participant exclusive intent on a target while others wait.
+ *   3. Stale-context (optimistic): a `readAt` watermark plus an `onStale` write
+ *      guard that catches a lost update when the row moved after you read it.
  *
- * Both the SDK (`types/streams.ts`) and the sync-server (`hub/types.ts`,
- * `presence/*`) derive their TypeScript types from THESE schemas via
- * `z.infer`, instead of re-declaring overlapping shapes. That collapses the
- * field drift this surface accreted — e.g. the SDK's claim view dropping
- * `status`/`error`, `onStale` declared 5×, `ClaimStatus` declared 2× — into
- * a single definition that the wire ingest can also validate at runtime.
+ * These Zod schemas are the single definition of each shape. Both the client
+ * SDK and the server derive their TypeScript types from them with `z.infer`
+ * rather than re-declaring the shapes, and the server validates inbound frames
+ * against them at runtime.
  */
 // ─────────────────────────────────────────────────────────────────────────
 //  Shared primitives
@@ -31,21 +28,20 @@ export const targetRangeSchema = z.object({
 });
 export const participantKindSchema = z.enum(['user', 'agent', 'system']);
 /**
- * Wire-tolerant participant kind for INGEST. The claim/presence streams
- * historically labelled a non-agent participant `'human'`, while the
- * capability/identity/lease surfaces all say `'user'` — the same participant,
- * two dialects. This normalizes the legacy `'human'` to the canonical `'user'`
- * on read so every consumer switches on ONE vocabulary. Producers emit
- * canonical {@link participantKindSchema} values; this only forgives an older
- * frame still carrying `'human'`. Additive — never widens the output union.
+ * Parses a participant kind from an inbound frame, tolerating an older wire
+ * dialect. Some presence and claim frames label a non-agent participant
+ * `'human'`, while the rest of the surface uses `'user'` for the same
+ * participant. This normalizes `'human'` to `'user'` on read so every consumer
+ * switches on one vocabulary. Producers emit the canonical
+ * {@link participantKindSchema} values, and the output union is never widened.
  */
 export const wireParticipantKindSchema = z.preprocess((value) => (value === 'human' ? 'user' : value), participantKindSchema);
 /**
- * Resolve a peer's kind from an inbound presence/claim frame. Prefers the
- * server-stamped `participantKind` (normalized via
- * {@link wireParticipantKindSchema}); frames from servers that predate the
- * field fall back to the lossy `isAgent` boolean — which can say 'agent' or
- * 'user' but never 'system' (the flatten this field exists to remove).
+ * Resolves a peer's kind from an inbound presence or claim frame. It prefers
+ * the server-stamped `participantKind` (normalized through
+ * {@link wireParticipantKindSchema}). A frame from an older server that omits
+ * that field falls back to the `isAgent` boolean, which can tell 'agent' from
+ * 'user' but can never report 'system'.
  */
 export function participantKindFromWire(wireKind, isAgent) {
     const parsed = wireParticipantKindSchema.safeParse(wireKind);
@@ -54,18 +50,18 @@ export function participantKindFromWire(wireKind, isAgent) {
     return isAgent ? 'agent' : 'user';
 }
 /**
- * The peer-visible explanation a claim/claim carries, lifted from its opaque
- * `meta.description`. One place for the `typeof meta?.description === 'string'`
- * unfold that the claim/claim/presence surfaces each re-implemented — callers
- * with an explicit `description` field still prefer it (`explicit ?? fromMeta`).
+ * Reads the peer-visible description a claim or presence frame carries in its
+ * opaque `meta.description`. This is the single place that unpacks that field.
+ * A caller that has an explicit `description` should prefer it
+ * (`explicit ?? fromMeta`).
  */
 export function descriptionFromMeta(meta) {
     return typeof meta?.description === 'string' ? meta.description : undefined;
 }
 /**
- * What a claim / claim / activity points at. The common locator shared by
- * all three layers — an entity, optionally narrowed to a path, range, or
- * field, with opaque app metadata.
+ * What a coordination event points at — the locator shared by all three
+ * layers. It names an entity, optionally narrowed to a path, range, or field,
+ * and carries opaque application metadata.
  */
 export const targetRefSchema = z.object({
     entityType: z.string(),
@@ -76,18 +72,17 @@ export const targetRefSchema = z.object({
     meta: z.record(z.string(), z.unknown()).optional(),
 });
 // ─────────────────────────────────────────────────────────────────────────
-//  Layer 3 — OPTIMISTIC stale-context (the write-guard)
+//  Layer 3 — optimistic stale-context (the write guard)
 // ─────────────────────────────────────────────────────────────────────────
 /**
- * Mode applied when a write's snapshot watermark (`readAt`) is older than the
- * target row's latest delta. Three dispositions, split by the non-coercion
- * convention (see docs/concurrency-convention.md):
- *   • `notify`    — NON-COERCIVE: hold the write, return a `StaleNotification`
- *                   with the current value; the actor (agent or human) resolves.
- *   • `reject`    — coercive escape hatch: throw `AbloStaleContextError`
- *                   (default when `readAt` is present).
- *   • `overwrite` — coercive escape hatch: apply blindly last-writer-wins, no
- *                   signal.
+ * How the server treats a write whose snapshot watermark (`readAt`) is older
+ * than the target row's latest change. There are three dispositions:
+ *   • `notify`    — hold the write and return a {@link StaleNotification}
+ *                   carrying the current value, so the actor (agent or human)
+ *                   can resolve it.
+ *   • `reject`    — throw `AbloStaleContextError`, the default when `readAt`
+ *                   is present.
+ *   • `overwrite` — apply the write blindly, last write wins, with no signal.
  */
 export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 /**
@@ -102,30 +97,23 @@ export const writeGuardSchema = z.object({
     bypass: z.boolean().optional(),
 });
 /**
- * The advisory signal returned to a committer whose write hit a stale-context
- * conflict under `onStale: 'notify'` — the engine's answer to "the typed value
- * you reasoned against changed while you were away."
+ * The advisory returned to a committer whose write hit a stale-context
+ * conflict under `onStale: 'notify'` — it reports that the value the committer
+ * reasoned against changed while they were away. Rather than throwing, the
+ * server hands back the conflicting field's current value as data so the
+ * actor — an agent or a human — can reconcile and re-commit. A claim is the
+ * prospective form of the same idea (coordinate before acting); this
+ * notification is the in-flight form (here is what changed, you resolve). It
+ * rides on the commit acknowledgement alongside `lastSyncId`; an empty or
+ * absent array means nothing the committer depended on moved.
  *
- * Philosophy: NON-COERCION. The engine's job is to surface the truthful current
- * state and let the intelligent actor — agent OR human — decide what to do; it
- * does NOT force an outcome. The two *forcing* dispositions are `reject`
- * (force-abort, discards the work) and `overwrite` (force-clobber). This
- * notification is the non-coercive path: instead of throwing, the server hands
- * back the conflicting field's *current* value as data so the actor can solve
- * it. The CLAIM is the prospective form of the same principle (coordinate
- * before acting); this notification is the in-flight form (here's what changed,
- * you resolve). Both an agent reasoning over the change and a human watching the
- * row are valid resolvers. (Cf. CoAgent/MTPO, arXiv:2606.15376, which bets the
- * resolver is specifically an LLM; Ablo's bet is the same non-coercion, actor
- * left to agent or human.) Rides on the commit ack alongside `lastSyncId`; an
- * empty/absent array means no premise moved.
- *
- * Only `notify` produces this: the conflicting op was HELD (not written), and
- * the actor reconciles against `currentValues` and re-commits. (`reject` throws,
- * `overwrite` is silent — neither notifies.)
+ * Only `onStale: 'notify'` produces this. The conflicting operation was held,
+ * not written, and the actor reconciles against `currentValues` and
+ * re-commits. `reject` throws instead, and `overwrite` proceeds silently —
+ * neither notifies.
  */
 export const staleNotificationSchema = z.object({
-    /** Stripe-style object tag — every returned object names its type. */
+    /** Names this object's type; every returned object carries such a tag. */
     object: z.literal('stale_notification').optional(),
     /** Model name of the conflicting row. */
     model: z.string(),
@@ -145,8 +133,8 @@ export const staleNotificationSchema = z.object({
      */
     conflictingFields: z.array(z.string()),
     /**
-     * Post-conflict live values of `conflictingFields` — the part a plain stale
-     * error never carried. Lets the LLM self-heal without a round-trip read.
+     * The live values of `conflictingFields` after the conflict — the piece a
+     * plain stale error omits. It lets the actor reconcile without a follow-up read.
      */
     currentValues: z.record(z.string(), z.unknown()),
     /** Who wrote the conflicting delta. */
@@ -164,18 +152,19 @@ export const staleNotificationSchema = z.object({
     group: z.string().optional(),
 });
 /**
- * A read DEPENDENCY declared on a commit — the STORM "did anything I looked at
- * change?" layer (vs. the write-target check that only validates the rows being
- * written). The server re-runs stale detection against each declared read at
- * `readAt`; a moved premise fires the entry's `onStale` disposition (default
- * `reject`) over the WHOLE batch (`notify` holds every write + notifies;
- * `reject` aborts; `overwrite` proceeds silently). Two granularities, choice:
+ * A read that a commit declares it depended on, so the server can ask "did
+ * anything I looked at change?" — broader than the write-target check, which
+ * only validates the rows being written. The server re-runs stale detection
+ * against each declared read at its `readAt`; a moved premise fires the entry's
+ * `onStale` disposition (default `reject`) across the whole batch (`notify`
+ * holds every write and notifies, `reject` aborts, `overwrite` proceeds
+ * silently). A dependency comes at one of two granularities:
  *
- *   • ROW   — `{ model, id, readAt, fields? }`: did this specific row (optionally
- *             these fields) change? The literal STORM/per-object premise.
- *   • GROUP — `{ group, readAt }`: did ANYTHING in this sync group change? `group`
- *             is a sync-group key like `deck:abc` or `slide:s1` — the same unit a
- *             human/agent watches and claims. Coarser, and more Ablo-native.
+ *   • Row   — `{ model, id, readAt, fields? }`: did this specific row, or these
+ *             specific fields, change?
+ *   • Group — `{ group, readAt }`: did anything in this sync group change?
+ *             `group` is a sync-group key such as `deck:abc` or `slide:s1`, the
+ *             same unit a participant watches and claims.
  */
 export const readDependencySchema = z.union([
     z.object({
@@ -192,14 +181,13 @@ export const readDependencySchema = z.union([
     }),
 ]);
 // ─────────────────────────────────────────────────────────────────────────
-//  Layer 2 — PESSIMISTIC claim / claim-lease
+//  Layer 2 — pessimistic claims and leases
 // ─────────────────────────────────────────────────────────────────────────
 /**
- * Lifecycle of an claim — the Stripe `PaymentIntent.status` shape. Absent on
- * the wire ⇒ `'active'` (additive back-compat). The server stamps `'active'`
- * on `claim_begin` and emits a single terminal frame (`committed` /
- * `canceled` / `expired`) as the claim ends, so contenders learn *how* it
- * resolved, not merely that it vanished.
+ * The lifecycle of a claim. When absent on the wire it means `'active'` (an
+ * additive back-compat default). The server stamps `'active'` on `claim_begin`
+ * and emits one terminal frame — `committed`, `canceled`, or `expired` — as the
+ * claim ends, so contenders learn how it resolved, not merely that it vanished.
  */
 export const claimStatusSchema = z.enum([
     'active',
@@ -241,16 +229,12 @@ export const claimErrorSchema = z.object({
     policyReason: z.string().optional(),
 });
 /**
- * A declared pending-mutation claim — the unit broadcast in presence
- * `activeClaims`. Clients supply the descriptive `targetRef` fields, an
- * explanatory `reason`, and a chosen `claimId`; the SERVER stamps `declaredAt` /
- * `expiresAt` and may set `status` / `error`.
- *
- * `status` and `error` are OPTIONAL: this single shape serves both the
- * server (which sets them) and the SDK view (which historically omitted
- * them). The superset is structurally assignable wherever the leaner view
- * was used, so the two prior copies collapse into this one without breaking
- * SDK consumers.
+ * A declared, pending-mutation claim — the unit broadcast inside a presence
+ * frame's `activeClaims`. The client supplies the descriptive `targetRef`
+ * fields, an explanatory `reason`, and a chosen `claimId`; the server stamps
+ * `declaredAt` and `expiresAt` and may set `status` and `error`. Those last
+ * two are optional, so one shape serves both the server, which sets them, and
+ * the leaner SDK view, which reads a claim without them.
  */
 export const wireClaimSchema = wireClaimBaseSchema.extend({
     error: claimErrorSchema.optional(),
@@ -266,9 +250,9 @@ export const claimRejectionSchema = z.object({
     policyReason: z.string().optional(),
 });
 /**
- * What a {@link ModelClaim} points at — the SDK-facing target locator, keyed by
- * `model`/`id` (the `ablo.<model>` vocabulary) rather than the wire's
- * `entityType`/`entityId`. Structurally the public `ModelTarget`.
+ * What a {@link ModelClaim} points at — the target locator as SDK callers see
+ * it, keyed by `model` and `id` rather than the wire schema's `entityType` and
+ * `entityId`. This is the public `ModelTarget` shape.
  */
 export const modelTargetSchema = z
     .object({
@@ -281,17 +265,16 @@ export const modelTargetSchema = z
 })
     .readonly();
 /**
- * A claim as surfaced to SDK callers and the HTTP claim routes
- * (`ablo.<model>.claim.state`, `/v1/claims`) — the resolved, peer-readable
- * view of one active or queued claim. The ONE canonical shape: the client
- * (`Ablo.ts`) derives its `ModelClaim` from this, and the sync-server's two
- * route copies adopt it once the engine dist is rebuilt.
+ * A claim as SDK callers and the HTTP claim routes see it
+ * (`ablo.<model>.claim.state`, `/v1/claims`) — the resolved, peer-readable view
+ * of one active or queued claim. The client's `ModelClaim` type derives from
+ * this shape.
  *
- * `expiresAt` is **epoch-ms** (a number) here — the same representation as the
- * WS `WireClaim`, so there is ONE timestamp encoding across wire, SDK, HTTP,
- * and errors (Stripe-style integer unix timestamps; no ISO string anywhere).
- * `participantKind` ingests via {@link wireParticipantKindSchema} so a legacy
- * `'human'` frame normalizes to `'user'`.
+ * `expiresAt` is epoch milliseconds (a number), the same encoding as the
+ * WebSocket {@link WireClaim}, so one timestamp representation spans the wire,
+ * the SDK, HTTP, and errors — there is no ISO string anywhere.
+ * `participantKind` is parsed through {@link wireParticipantKindSchema}, so a
+ * legacy `'human'` frame normalizes to `'user'`.
  */
 export const modelClaimSchema = z
     .object({
@@ -309,10 +292,10 @@ export const modelClaimSchema = z
 })
     .readonly();
 /**
- * `claim_begin` payload (client → server). The descriptive target + reason,
- * plus an optional duration hint and the opt-in fair-queue flag. The server
- * stamps the lifecycle/timestamp fields, so they are NOT part of the inbound
- * shape — this is exactly what the WS ingest validates.
+ * The `claim_begin` payload a client sends. It carries the descriptive target
+ * and reason, an optional duration hint, and the opt-in fair-queue flag. The
+ * server stamps the lifecycle and timestamp fields, so they are not part of
+ * this inbound shape — this is exactly what the server validates on ingest.
  */
 export const claimBeginPayloadSchema = targetRefSchema.extend({
     claimId: z.string(),
@@ -320,19 +303,17 @@ export const claimBeginPayloadSchema = targetRefSchema.extend({
     /** Hint for `expiresAt`; the server caps it. */
     estimatedMs: z.number().optional(),
     /**
-     * Opt into the fair wait queue: when the target is already held, the server
-     * enqueues this claim (FIFO) and replies `claim_queued` → later
-     * `claim_granted`, instead of `claim_rejected`. Clients that set this MUST
-     * handle the grant.
+     * Opt into the fair wait queue. When the target is already held, the server
+     * enqueues this claim in FIFO order and replies `claim_queued`, then
+     * `claim_granted` later, instead of `claim_rejected`. A client that sets this
+     * must be ready to handle the grant.
      */
     queue: z.boolean().optional(),
 });
 /**
- * `claim_abandon` payload (client → server). `entityType`/`entityId` are
- * carried so the server can DEQUEUE a still-*waiting* (not held) claim from
- * the FIFO line — the held-claim path needs only `claimId`. (The previous
- * wire type omitted these two even though the handler reads them; the schema
- * documents what the code actually uses.)
+ * The `claim_abandon` payload a client sends. `entityType` and `entityId` let
+ * the server dequeue a claim that is still waiting (not yet held) from the FIFO
+ * line; abandoning a claim that is already held needs only `claimId`.
  */
 export const claimAbandonPayloadSchema = z.object({
     claimId: z.string(),
@@ -340,13 +321,13 @@ export const claimAbandonPayloadSchema = z.object({
     entityId: z.string().optional(),
 });
 /**
- * `claim_reorder` payload (client → server). A privileged participant (e.g. a
- * supervisor over its sub-agents) re-ranks the FIFO wait queue for an entity:
- * `order` lists waiters by `heldBy`+`claimId` in the desired priority. Waiters
- * not listed keep their relative order behind the listed ones. The server gates
- * who may call this; an unauthorized sender is dropped. Unlike `claim_abandon`
- * (acts on the caller's own entry), reorder acts on OTHER participants' queue
- * positions — hence the authorization gate.
+ * The `claim_reorder` payload a client sends. A privileged participant, such as
+ * a supervisor over its sub-agents, re-ranks the FIFO wait queue for an entity:
+ * `order` lists waiters by `heldBy` and `claimId` in the desired priority, and
+ * any waiter not listed keeps its relative order behind those that are. The
+ * server gates who may call this and drops an unauthorized sender. Where
+ * `claim_abandon` acts on the caller's own entry, a reorder acts on other
+ * participants' queue positions — which is why it is gated.
  */
 export const claimReorderPayloadSchema = z.object({
     entityType: z.string(),
@@ -354,15 +335,98 @@ export const claimReorderPayloadSchema = z.object({
     order: z.array(z.object({ heldBy: z.string(), claimId: z.string() })),
 });
 // ─────────────────────────────────────────────────────────────────────────
+//  Heartbeat — the async / long-running-work surface of a claim.
+//
+//  A claim's TTL is crash cleanup, not a work-duration estimate. Work that
+//  outlives it — an agent run, a background worker's job — keeps its lease by
+//  BEATING: request `claim_heartbeat`, reply `claim_heartbeat_ack`. One field
+//  set serves every shape; the single and batched payloads are both derived
+//  from it, and the WebSocket frame and HTTP routes are two encodings of the
+//  same messages. Everything long-running-work-related on the wire lives in
+//  this block.
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * The one field set behind every heartbeat message. The single-claim payload
+ * refines it; the batched payload picks from it — there is deliberately no
+ * second shape to keep in sync.
+ */
+const claimHeartbeatFieldsSchema = z.object({
+    claimId: z.string().optional(),
+    entityType: z.string().optional(),
+    entityId: z.string().optional(),
+    /** Requested extension from now; the server clamps it, and an extension
+     *  never shortens a lease. */
+    ttlMs: z.number().positive().optional(),
+    /**
+     * Lightweight progress the beat carries along ("42/100 pages") — stored
+     * as the claim's `meta.progress` (last beat wins) and peer-visible via
+     * `claim.state` while the lease is held. This is presence, not a
+     * checkpoint: it dies with the lease. Crash-recoverable progress belongs
+     * in the data itself — write a row, and every subscriber already sees it.
+     */
+    details: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * The `claim_heartbeat` payload a client sends to extend a lease it holds (or
+ * refresh its slot in the wait queue) past the liveness window — the
+ * work-duration signal for long-running holders, distinct from the connection
+ * keepalive.
+ *
+ * The claim is identified either way: by `claimId`, or — since a claim is
+ * singular per (actor, entity) — by the full `entityType`/`entityId` target
+ * ("my claim on this row"). At least one of the two must be present. The
+ * target also lets the server resolve without a scan and is required to
+ * refresh a *queued* claim (a waiter is not in the holder set the server
+ * would otherwise search).
+ */
+export const claimHeartbeatPayloadSchema = claimHeartbeatFieldsSchema.refine((payload) => payload.claimId !== undefined ||
+    (payload.entityType !== undefined && payload.entityId !== undefined), {
+    message: 'a heartbeat must identify its claim — pass claimId, or entityType and entityId together',
+});
+/**
+ * The server's reply to a `claim_heartbeat`. For a socketless worker the
+ * heartbeat reply is the only inbound signal path, so it carries the lease's
+ * fate rather than a bare ok: `held` (extended to `expiresAt`), `queued`
+ * (slot refreshed; `position` is the current place in line), or `lost` (the
+ * lease expired and the queue moved on — the worker should abandon or
+ * re-queue, and any write it still attempts is caught by its `readAt` guard).
+ */
+export const claimHeartbeatAckPayloadSchema = z.object({
+    claimId: z.string(),
+    status: z.enum(['held', 'queued', 'lost']),
+    expiresAt: z.number().optional(),
+    position: z.number().optional(),
+    /**
+     * How many participants are waiting in line behind a held lease — the
+     * cooperative-yield pressure signal (present on `held`). A worker that can
+     * checkpoint may choose to release early when others wait. Hard
+     * cancellation needs no extra field: a preempted, expired, or revoked
+     * lease answers the next beat with `lost`.
+     */
+    queueDepth: z.number().optional(),
+});
+/**
+ * The batched heartbeat — one request extends every lease the caller holds
+ * on its plane (the socketless twin of the WebSocket keepalive, which renews
+ * all held leases on every ping). For a worker holding many rows this is one
+ * round trip per cadence instead of one per claim. Queued slots are not
+ * batch-refreshed: a waiter knows its target and beats it directly.
+ */
+export const claimHeartbeatBatchPayloadSchema = claimHeartbeatFieldsSchema.pick({ ttlMs: true });
+/** Reply to a batched heartbeat: one ack entry per lease that was extended. */
+export const claimHeartbeatBatchAckPayloadSchema = z.object({
+    results: z.array(claimHeartbeatAckPayloadSchema),
+});
+// ─────────────────────────────────────────────────────────────────────────
 //  Read interest — area-of-interest navigation (update_subscription)
 // ─────────────────────────────────────────────────────────────────────────
 /**
- * `update_subscription` payload (client → server). Replaces the connection's
- * connection-level read interest with the COMPLETE set of sync groups — the
- * READ counterpart to a claim (no write-claim, no TTL). Each entry is a
+ * The `update_subscription` payload a client sends. It replaces the
+ * connection's read interest with the complete set of sync groups — the read
+ * counterpart to a claim, with no write lock and no TTL. Each entry is a
  * {@link syncGroupInputSchema} (`'default'` or a branded `kind:id`), so a
- * malformed group is rejected at ingest instead of being silently indexed.
- * This is untrusted client input, so the element type is strict.
+ * malformed group is rejected on ingest rather than silently indexed. The
+ * element type is strict because this is untrusted client input.
  */
 export const updateSubscriptionPayloadSchema = z.object({
     syncGroups: z.array(syncGroupInputSchema),
@@ -405,7 +469,7 @@ export const commitOperationSchema = writeGuardSchema.extend({
     transactionId: z.string().nullish(),
 });
 // ─────────────────────────────────────────────────────────────────────────
-//  Layer 1 — PRESENCE (observation only; never enforces)
+//  Layer 1 — presence (observation only; it never enforces)
 // ─────────────────────────────────────────────────────────────────────────
 export const presenceKindSchema = z.enum(['enter', 'update', 'leave']);
 /** What a participant is actively working on (agents fill this in). */

package/dist/coordination/trace.d.ts

@@ -1,14 +1,13 @@
 /**
- * Claim log — the easy way to SEE agents colliding.
+ * A claim log — the simplest way to watch agents collide. The engine reports
+ * the claim lifecycle (`acquired → queued → granted → lost / rejected /
+ * expired`) and the notify-instead-of-abort stale write through two channels:
+ * human-readable `logger` lines (shown with `new Ablo({ debug: true })`) and
+ * structured `observability.captureClaim` / `captureConflict` calls.
  *
- * The engine emits the claim lifecycle (`acquired → queued → granted → lost /
- * rejected / expired`) and the notify-instead-of-abort stale-write collision
- * through two seams: human `logger` lines (visible with `new Ablo({ debug: true })`)
- * and structured `observability.captureClaim` / `captureConflict` calls.
- *
- * This is the third, evals-shaped path: hand a {@link ClaimLog} to
- * `Ablo({ observability })`, run your scenario, then read back an ordered list
- * you can print for eyeballing or `collisions()` for assertions.
+ * This is a third channel, shaped for tests and evals. Pass a {@link ClaimLog}
+ * as `Ablo({ observability })`, run your scenario, then read back an ordered
+ * list — print it to eyeball what happened, or call `collisions()` to assert on it.
  */
 import type { SyncObservabilityProvider, ClaimEvent, ConflictEvent } from '../interfaces/index.js';
 /** A claim state change as one quiet, greppable line. */
@@ -19,7 +18,7 @@ export declare function formatConflict(e: ConflictEvent): string;
 export interface ClaimLogEntry {
     /** Monotonic order index — deterministic, clock-free, eval-friendly. */
     readonly seq: number;
-    /** The same one-line text the console and breadcrumb seams emit. */
+    /** The same one-line text the console and breadcrumb channels emit. */
     readonly line: string;
     /** A collision worth flagging: a rejected/lost claim or a stale write. */
     readonly collision: boolean;

package/dist/coordination/trace.js

@@ -1,18 +1,17 @@
 /**
- * Claim log — the easy way to SEE agents colliding.
+ * A claim log — the simplest way to watch agents collide. The engine reports
+ * the claim lifecycle (`acquired → queued → granted → lost / rejected /
+ * expired`) and the notify-instead-of-abort stale write through two channels:
+ * human-readable `logger` lines (shown with `new Ablo({ debug: true })`) and
+ * structured `observability.captureClaim` / `captureConflict` calls.
  *
- * The engine emits the claim lifecycle (`acquired → queued → granted → lost /
- * rejected / expired`) and the notify-instead-of-abort stale-write collision
- * through two seams: human `logger` lines (visible with `new Ablo({ debug: true })`)
- * and structured `observability.captureClaim` / `captureConflict` calls.
- *
- * This is the third, evals-shaped path: hand a {@link ClaimLog} to
- * `Ablo({ observability })`, run your scenario, then read back an ordered list
- * you can print for eyeballing or `collisions()` for assertions.
+ * This is a third channel, shaped for tests and evals. Pass a {@link ClaimLog}
+ * as `Ablo({ observability })`, run your scenario, then read back an ordered
+ * list — print it to eyeball what happened, or call `collisions()` to assert on it.
  */
 // ─────────────────────────────────────────────
-// Formatters — one readable line per event. Shared by the WS logger seam and
-// the log so console output and log output never drift.
+// Formatters — one readable line per event. Shared by the debug logger and
+// this log so console output and log output never drift.
 // ─────────────────────────────────────────────
 /** A claim state change as one quiet, greppable line. */
 export function formatClaim(e) {
@@ -22,7 +21,7 @@ export function formatClaim(e) {
     const actor = e.actor
         ? `${e.actor}${e.participantKind ? ` (${e.participantKind})` : ''}`
         : '';
-    // `rejected`/`lost` name the BLOCKING holder; the rest name us (or no one).
+    // `rejected`/`lost` name the blocking holder; the rest name us (or no one).
     const by = actor
         ? e.phase === 'rejected' || e.phase === 'lost'
             ? ` — held by ${actor}`
@@ -54,7 +53,7 @@ export function formatConflict(e) {
  */
 export class ClaimLog {
     max;
-    // Immutable list: a NEW array reference on every change. This is what lets
+    // Immutable list: a new array reference on every change. This is what lets
     // `useSyncExternalStore(log.onChange, () => log.entries)` detect updates —
     // it compares snapshots by reference, so an in-place push would never render.
     rows = [];
@@ -64,7 +63,7 @@ export class ClaimLog {
     constructor(max = 1_000) {
         this.max = max;
     }
-    // —— the two seams we record ——
+    // —— the two channels we record ——
     captureClaim(claim) {
         this.add({
             line: formatClaim(claim),

package/dist/core/DatabaseManager.d.ts

@@ -1,11 +1,9 @@
 /**
- * Ablo Sync Engine - Database Manager
- *
- * Manages the two-tier database architecture:
- * 1. ablo_databases - Metadata about workspace databases
- * 2. ablo_(hash) - Workspace-specific data storage
- *
- * Follows Ablo's architecture for database management.
+ * Manages the client-side IndexedDB databases the sync engine keeps in the
+ * browser. There are two tiers. A single registry database, `ablo_databases`,
+ * records metadata about every workspace database. Each user-and-workspace pair
+ * then gets its own data database, named `ablo_<hash>`, that holds the synced
+ * rows. {@link DatabaseManager} creates, versions, and deletes both tiers.
  */
 export interface DatabaseInfo {
     name: string;