@abloatai/ablo 0.26.0 → 0.27.0

package/dist/coordination/schema.d.ts

@@ -1,22 +1,19 @@
 import { z } from 'zod';
 /**
- * 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.
  */
 /** A line/column span within a text-bearing field (slide body, doc, cell). */
 export declare const targetRangeSchema: z.ZodObject<{
@@ -33,13 +30,12 @@ export declare const participantKindSchema: z.ZodEnum<{
 }>;
 export type ParticipantKind = z.infer<typeof participantKindSchema>;
 /**
- * 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 declare const wireParticipantKindSchema: z.ZodPreprocess<z.ZodEnum<{
     user: "user";
@@ -47,24 +43,24 @@ export declare const wireParticipantKindSchema: z.ZodPreprocess<z.ZodEnum<{
     system: "system";
 }>>;
 /**
- * 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 declare function participantKindFromWire(wireKind: unknown, isAgent: boolean | undefined): ParticipantKind;
 /**
- * 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 declare function descriptionFromMeta(meta: Record<string, unknown> | undefined | null): string | 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 declare const targetRefSchema: z.ZodObject<{
     entityType: z.ZodString;
@@ -81,15 +77,14 @@ export declare const targetRefSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type TargetRef = z.infer<typeof targetRefSchema>;
 /**
- * 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 declare const onStaleModeSchema: z.ZodEnum<{
     reject: "reject";
@@ -114,27 +109,20 @@ export declare const writeGuardSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type WriteGuard = z.infer<typeof writeGuardSchema>;
 /**
- * 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 declare const staleNotificationSchema: z.ZodObject<{
     object: z.ZodOptional<z.ZodLiteral<"stale_notification">>;
@@ -156,18 +144,19 @@ export declare const staleNotificationSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type StaleNotification = z.infer<typeof staleNotificationSchema>;
 /**
- * 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 declare const readDependencySchema: z.ZodUnion<readonly [z.ZodObject<{
     model: z.ZodString;
@@ -190,11 +179,10 @@ export declare const readDependencySchema: z.ZodUnion<readonly [z.ZodObject<{
 }, z.core.$strip>]>;
 export type ReadDependency = z.infer<typeof readDependencySchema>;
 /**
- * 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 declare const claimStatusSchema: z.ZodEnum<{
     active: "active";
@@ -235,16 +223,12 @@ export declare const claimErrorSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ClaimError = z.infer<typeof claimErrorSchema>;
 /**
- * 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 declare const wireClaimSchema: z.ZodObject<{
     entityType: z.ZodString;
@@ -321,9 +305,9 @@ export declare const claimRejectionSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ClaimRejection = z.infer<typeof claimRejectionSchema>;
 /**
- * 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 declare const modelTargetSchema: z.ZodReadonly<z.ZodObject<{
     model: z.ZodString;
@@ -340,17 +324,16 @@ export declare const modelTargetSchema: z.ZodReadonly<z.ZodObject<{
 }, z.core.$strip>>;
 export type ModelTarget = z.infer<typeof modelTargetSchema>;
 /**
- * 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 declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
     id: z.ZodString;
@@ -385,10 +368,10 @@ export declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
 }, z.core.$strip>>;
 export type ModelClaim = z.infer<typeof modelClaimSchema>;
 /**
- * `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 declare const claimBeginPayloadSchema: z.ZodObject<{
     entityType: z.ZodString;
@@ -409,11 +392,9 @@ export declare const claimBeginPayloadSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ClaimBeginPayload = z.infer<typeof claimBeginPayloadSchema>;
 /**
- * `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 declare const claimAbandonPayloadSchema: z.ZodObject<{
     claimId: z.ZodString;
@@ -422,13 +403,13 @@ export declare const claimAbandonPayloadSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ClaimAbandonPayload = z.infer<typeof claimAbandonPayloadSchema>;
 /**
- * `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 declare const claimReorderPayloadSchema: z.ZodObject<{
     entityType: z.ZodString;
@@ -440,12 +421,79 @@ export declare const claimReorderPayloadSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ClaimReorderPayload = z.infer<typeof claimReorderPayloadSchema>;
 /**
- * `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 `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 declare const claimHeartbeatPayloadSchema: z.ZodObject<{
+    claimId: z.ZodOptional<z.ZodString>;
+    entityType: z.ZodOptional<z.ZodString>;
+    entityId: z.ZodOptional<z.ZodString>;
+    ttlMs: z.ZodOptional<z.ZodNumber>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ClaimHeartbeatPayload = z.infer<typeof claimHeartbeatPayloadSchema>;
+/**
+ * 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 declare const claimHeartbeatAckPayloadSchema: z.ZodObject<{
+    claimId: z.ZodString;
+    status: z.ZodEnum<{
+        queued: "queued";
+        held: "held";
+        lost: "lost";
+    }>;
+    expiresAt: z.ZodOptional<z.ZodNumber>;
+    position: z.ZodOptional<z.ZodNumber>;
+    queueDepth: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ClaimHeartbeatAckPayload = z.infer<typeof claimHeartbeatAckPayloadSchema>;
+/**
+ * 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 declare const claimHeartbeatBatchPayloadSchema: z.ZodObject<{
+    ttlMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ClaimHeartbeatBatchPayload = z.infer<typeof claimHeartbeatBatchPayloadSchema>;
+/** Reply to a batched heartbeat: one ack entry per lease that was extended. */
+export declare const claimHeartbeatBatchAckPayloadSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        claimId: z.ZodString;
+        status: z.ZodEnum<{
+            queued: "queued";
+            held: "held";
+            lost: "lost";
+        }>;
+        expiresAt: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodNumber>;
+        queueDepth: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ClaimHeartbeatBatchAckPayload = z.infer<typeof claimHeartbeatBatchAckPayloadSchema>;
+/**
+ * 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 declare const updateSubscriptionPayloadSchema: z.ZodObject<{
     syncGroups: z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"default">, z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">]>>;
@@ -504,11 +552,11 @@ export declare const commitOperationSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type CommitOperation = z.infer<typeof commitOperationSchema>;
 /**
- * Any commit op on the wire — the runtime-validated ingest contract. Commit
- * ops carry replace (last-write-wins) semantics, guarded by the optimistic
- * `writeGuard`. Kept as a distinct alias from {@link CommitOperation} so the
- * ingest boundary in the server reads as "any op on the wire" even though the
- * two are currently structurally identical.
+ * Any commit operation on the wire — the runtime-validated ingest contract.
+ * Commit operations carry replace (last-write-wins) semantics, guarded by the
+ * optimistic write guard. It is a distinct alias from {@link CommitOperation}
+ * so the server's ingest boundary reads as "any op on the wire", even though
+ * the two shapes are identical.
  */
 export type AnyCommitOperation = CommitOperation;
 export declare const presenceKindSchema: z.ZodEnum<{