@abloatai/ablo 0.34.1 → 0.35.0

package/dist/{coordination → transaction/coordination}/schema.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { syncGroupInputSchema } from '../schema/roles.js';
 /**
- * The wire schemas for coordination — the shapes that keep humans and agents
+ * The wire schemas for coordination — the shapes that keep agents and people
  * from overwriting each other on a shared row. Coordination works in three
  * layers, from outermost to innermost:
  *
@@ -19,7 +19,7 @@ import { syncGroupInputSchema } from '../schema/roles.js';
 // ─────────────────────────────────────────────────────────────────────────
 //  Shared primitives
 // ─────────────────────────────────────────────────────────────────────────
-/** A line/column span within a text-bearing field (slide body, doc, cell). */
+/** A line/column span within a text-bearing field (section body, doc, cell). */
 export const targetRangeSchema = z.object({
     startLine: z.number(),
     endLine: z.number(),
@@ -27,6 +27,8 @@ export const targetRangeSchema = z.object({
     endColumn: z.number().optional(),
 });
 export const participantKindSchema = z.enum(['user', 'agent', 'system']);
+const _participantKindContract = true;
+void _participantKindContract;
 /**
  * Parses a participant kind from an inbound frame, tolerating an older wire
  * dialect. Some presence and claim frames label a non-agent participant
@@ -54,9 +56,43 @@ export function participantKindFromWire(wireKind, isAgent) {
  * opaque `meta.description`. This is the single place that unpacks that field.
  * A caller that has an explicit `description` should prefer it
  * (`explicit ?? fromMeta`).
+ *
+ * The parameter is `unknown` because that is the honest requirement: this reads
+ * one optional string off a value it does not own. Demanding the wire's open
+ * record instead forced every caller holding a claim's *declared* `meta` — the
+ * shape registered on `Register`'s `ClaimMeta` slot — through a conversion to
+ * ask a question that never needed one.
  */
 export function descriptionFromMeta(meta) {
-    return typeof meta?.description === 'string' ? meta.description : undefined;
+    if (typeof meta !== 'object' || meta === null)
+        return undefined;
+    if (!('description' in meta))
+        return undefined;
+    const { description } = meta;
+    return typeof description === 'string' ? description : undefined;
+}
+/** The default a claim carries when its holder describes no work. */
+export const DEFAULT_CLAIM_DESCRIPTION = 'editing';
+/**
+ * Resolves the peer-visible description of a claim from the places a caller may
+ * have put it, falling back to a plain default.
+ *
+ * `reason` was this field's name before it was renamed, and the rename shipped
+ * without leaving anything behind — so the wire kept accepting both spellings
+ * while the SDK type quietly offered only one, and two branches "fixed" the
+ * gap in opposite directions without either being contradicted by a compiler.
+ * The precedence is declared once, here, and both the client and the server
+ * read it from this function rather than each spelling out the same `??` chain.
+ *
+ * A caller whose default differs — a claim taken around a `create` describes
+ * itself as `'creating'` — passes that word as `fallback`; the precedence above
+ * it stays this function's.
+ */
+export function claimDescription(source, fallback = DEFAULT_CLAIM_DESCRIPTION) {
+    return (source.description ??
+        descriptionFromMeta(source.meta) ??
+        source.reason ??
+        fallback);
 }
 /**
  * What a coordination event points at — the locator shared by all three
@@ -69,8 +105,34 @@ export const targetRefSchema = z.object({
     path: z.string().optional(),
     range: targetRangeSchema.optional(),
     field: z.string().optional(),
+    /**
+     * Several named parts of one row, claimed together — three sections of a
+     * document, two cells of a table.
+     *
+     * This exists because there was no way to say it. A caller who needed it
+     * packed the set into `field` as one delimited string, and the conflict rule
+     * compares `field` for equality: `blocks:b_1` and `blocks:b_1,b_2` read as
+     * unrelated targets, so both writers were granted a lease on `b_1` and one
+     * of their updates was lost with nothing raised. A set compares as a set —
+     * overlapping sets conflict, disjoint sets do not.
+     *
+     * `field` remains for the single-field case and is read as a set of one, so
+     * a claim naming `field` and a claim naming `fields` still compare correctly
+     * against each other.
+     */
+    fields: z.array(z.string()).readonly().optional(),
     meta: z.record(z.string(), z.unknown()).optional(),
 });
+/**
+ * The same locator in the spelling the wait line and the claim handle use —
+ * `{ type, id }` for the entity, the sub-entity half unchanged. It is a
+ * projection of {@link targetRefSchema} rather than a second declaration, so a
+ * member added to the locator reaches the wait line without anyone editing it;
+ * a hand-written copy here is how `fields` came to be missing from queue frames.
+ */
+const streamTargetSchema = targetRefSchema
+    .omit({ entityType: true, entityId: true })
+    .extend({ type: z.string(), id: z.string() });
 // ─────────────────────────────────────────────────────────────────────────
 //  Layer 3 — optimistic stale-context (the write guard)
 // ─────────────────────────────────────────────────────────────────────────
@@ -143,8 +205,8 @@ export const staleNotificationSchema = z.object({
         id: z.string(),
     }),
     /**
-     * Set when this notification is for a GROUP read-dependency (e.g. `deck:abc`,
-     * `slide:s1`) rather than a single row — "something in the group you read
+     * Set when this notification is for a GROUP premise (e.g. `report:abc`,
+     * `section:s1`) rather than a single row — "something in the group you read
      * changed." For a group notification `conflictingFields`/`currentValues` are
      * empty (the change could span many rows); re-read the group at
      * `observedSyncId` to reconcile. Absent ⇒ a row-scoped notification.
@@ -152,18 +214,18 @@ export const staleNotificationSchema = z.object({
     group: z.string().optional(),
 });
 /**
- * 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:
+ * One entry in a commit's batch premise — a read it was based 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 entry 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). An entry comes at one of two granularities:
  *
  *   • 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
+ *             `group` is a sync-group key such as `report:abc` or `section:s1`, the
  *             same unit a participant watches and claims.
  *
  * See `packages/sync-engine/docs/concurrency-convention.md` (§4) for the
@@ -174,7 +236,7 @@ export const readDependencySchema = z.union([
         model: z.string(),
         id: z.string(),
         readAt: z.number(),
-        fields: z.array(z.string()).optional(),
+        fields: z.array(z.string()).readonly().optional(),
         onStale: onStaleModeSchema.optional(),
     }),
     z.object({
@@ -184,15 +246,16 @@ export const readDependencySchema = z.union([
     }),
 ]);
 /**
- * A durable read-dependency — what a participant is watching so that a later
+ * A durable premise — what a participant is watching so that a later
  * change to it opens a {@link StaleNotification}. It is the persisted sibling of
  * a {@link ReadDependency}: the same reference shape, minus the disposition (a
  * track always notifies — that is what tracking is), with an optional `readAt`
  * that defaults to the watermark of the commit that registered it. The row form
  * watches one object; the group form watches a whole sync group ("anything in
- * `deck:abc`"). Where a `ReadDependency` is checked once at commit and discarded,
- * a `TrackDependency` is kept and re-checked against every future delta. See
- * `packages/sync-engine/docs/groups.md` for how it drives change propagation.
+ * `report:abc`"). Where a `ReadDependency` is checked once at commit and
+ * discarded, a `TrackDependency` is kept and re-checked against every future
+ * delta. See `packages/sync-engine/docs/groups.md` for how it drives change
+ * propagation.
  */
 export const trackDependencySchema = z.union([
     z.object({
@@ -214,12 +277,37 @@ export const trackDependencySchema = z.union([
  * 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([
+export const wireClaimStatusSchema = z.enum([
     'active',
     'committed',
     'expired',
     'canceled',
 ]);
+/**
+ * Every lifecycle state of a claim, as a caller sees it.
+ *
+ * `active` is the current holder — the lock itself. `queued` is waiting in line
+ * behind the holder and carries an advisory `position`. The rest are terminal
+ * and drop the claim from the synced set.
+ *
+ * Distinct from {@link wireClaimStatusSchema}, which never carries `queued`
+ * because the wire frame for a waiter is a different message. This is the one a
+ * published contract describes, so it is a schema rather than a bare TS union —
+ * a union cannot be derived into the API reference.
+ */
+export const publicClaimStatusSchema = z.enum([
+    'active',
+    'queued',
+    'committed',
+    'expired',
+    'canceled',
+]);
+/**
+ * @deprecated Renamed to {@link wireClaimStatusSchema} — this is the wire enum,
+ * which never carries `'queued'`; the five-state public status lives in
+ * types/streams. Removed in 0.36.0.
+ */
+export const claimStatusSchema = wireClaimStatusSchema;
 /**
  * Server-owned grant stamps — minted once when a claim is first granted and
  * preserved verbatim across a re-announce of the same `claimId`, so neither a
@@ -242,7 +330,18 @@ const grantStampFields = {
      */
     acquiredAt: z.number().optional(),
 };
-const wireClaimBaseSchema = targetRefSchema.extend({
+/**
+ * A holder as the participant blocked behind them sees it: who has the row,
+ * what they said they are doing, and until when.
+ *
+ * This is the smaller half of a claim, so it is declared first and the full
+ * claim extends it — the waiter's view cannot omit a member the holder's view
+ * has, because there is nowhere for it to be omitted. Listing what to keep was
+ * the bug: this named `field` and not `path`, `range`, or `fields`, so a waiter
+ * could see that a row was held but never which part of it, and every locator
+ * member added later would have been missing here too.
+ */
+export const wireClaimSummarySchema = targetRefSchema.extend({
     claimId: z.string(),
     /**
      * Peer-visible description of the work being done (`'rewriting the risk
@@ -254,18 +353,30 @@ const wireClaimBaseSchema = targetRefSchema.extend({
     declaredAt: z.number(),
     /** Server-computed TTL deadline (epoch ms). Readers treat as advisory. */
     expiresAt: z.number(),
-    status: claimStatusSchema.optional(),
-    ...grantStampFields,
+    /**
+     * On whose authority the holder acts, and under which grant — stamped by the
+     * server off the connection's credential, never accepted from the frame. The
+     * same three fields the delta this claim produces will record, so "who is
+     * doing this" and "who did this" answer in one vocabulary.
+     *
+     * On the summary rather than the full claim because this is precisely what a
+     * blocked waiter needs: yielding to a colleague and queuing behind another
+     * customer's agent are different decisions.
+     *
+     * All three optional and additive — an older server omits them, which is a
+     * different fact from a holder that has no delegator.
+     */
+    onBehalfOfId: z.string().nullish(),
+    onBehalfOfKind: wireParticipantKindSchema.nullish(),
+    capabilityId: z.string().nullish(),
 });
-export const wireClaimSummarySchema = wireClaimBaseSchema.pick({
-    claimId: true,
-    description: true,
-    declaredAt: true,
-    expiresAt: true,
-    entityType: true,
-    entityId: true,
-    field: true,
-    meta: true,
+/**
+ * The full claim as its holder's own frames carry it — the waiter's view plus
+ * the lifecycle and grant stamps that belong to the holding itself.
+ */
+const wireClaimBaseSchema = wireClaimSummarySchema.extend({
+    status: wireClaimStatusSchema.optional(),
+    ...grantStampFields,
 });
 /** Why a claim ended in a non-success terminal state. */
 export const claimErrorSchema = z.object({
@@ -296,6 +407,14 @@ export const claimRejectionSchema = z.object({
     reason: z.string(),
     target: targetRefSchema.optional(),
     heldBy: z.string().optional(),
+    /**
+     * Whether the holder blocking this claim is a person, an agent, or the
+     * system. The server already derives this from the holder's id when it
+     * builds the conflict; carrying it means a caller can decide how to respond
+     * — yield to a person, queue behind an agent — without parsing an opaque id
+     * for a prefix and guessing. Additive: an older server omits it.
+     */
+    heldByKind: wireParticipantKindSchema.optional(),
     heldByClaimId: z.string().optional(),
     heldByExpiresAt: z.number().optional(),
     heldByClaim: wireClaimSummarySchema.optional(),
@@ -312,6 +431,120 @@ export const claimLostSchema = z.object({
     reason: z.enum(['expired', 'preempted']),
     target: targetRefSchema,
 });
+/**
+ * The lease is ours without waiting — the target was free when the claim
+ * arrived. `fenceToken` is present whenever the coordinator minted one, and a
+ * write carries it back so a lapsed lease cannot apply late.
+ */
+export const claimAcquiredSchema = z.object({
+    claimId: z.string(),
+    fenceToken: z.number().optional(),
+    target: targetRefSchema,
+});
+/**
+ * A queued claim reached the head of the line and the lease is now ours. The
+ * shape matches {@link claimAcquiredSchema} exactly — the two frames differ
+ * only in whether the caller waited — but they stay separate declarations
+ * because they are separate wire contracts, and collapsing them would let a
+ * change to one silently redefine the other.
+ */
+export const claimGrantedSchema = z.object({
+    claimId: z.string(),
+    fenceToken: z.number().optional(),
+    target: targetRefSchema,
+});
+/**
+ * Our claim is waiting in line behind a live holder — the same conflict
+ * {@link claimRejectionSchema} reports, delivered as a wait rather than a
+ * refusal, plus the caller's `position`.
+ *
+ * `reason` is the one member that does not carry over as required. A refusal
+ * states why it refused; a wait has only ever named the conflict through
+ * `heldBy`/`heldByClaim`, and no server has ever stamped `reason` on this
+ * frame. Requiring it here — inherited silently by extending the rejection
+ * schema — made the parse boundary reject every genuine `claim_queued` as
+ * malformed the moment frame validation went in. Optional is what the wire
+ * actually is, and it stays derived from the rejection field so the two cannot
+ * describe the value differently.
+ *
+ * `position` is advisory: a privileged reorder can move it up, so a caller
+ * that asserts monotonic position will fail in production. Only the arrival of
+ * a grant is authoritative.
+ */
+export const claimQueuedSchema = claimRejectionSchema.extend({
+    position: z.number(),
+    reason: claimRejectionSchema.shape.reason.optional(),
+});
+/**
+ * One entry in a wait-line snapshot.
+ *
+ * NOTE — this is the third spelling of a target locator on the wire: here it is
+ * `{ type, id }`, the HTTP claim DTO uses `{ model, id }`
+ * ({@link modelTargetSchema}), and the claim frames use
+ * `{ entityType, entityId }` ({@link targetRefSchema}). The schema describes
+ * what the server sends today rather than what it should send; unifying the
+ * three is a coordinated protocol change scheduled behind the protocol version.
+ * Until it happens, the translation between the spellings lives in one place —
+ * `wireTarget`, `modelTarget` and `streamTarget` in ./locator.ts — so no hop
+ * gets to invent a fourth.
+ */
+export const claimQueueEntrySchema = z.object({
+    object: z.literal('claim'),
+    id: z.string(),
+    status: z.literal('queued'),
+    target: streamTargetSchema,
+    /**
+     * Peer-visible description of the work. A claim may be declared without one,
+     * and the public `Claim` promises the field is always there — so the default
+     * lives here, applied as the frame is decoded, rather than being restated by
+     * each reader.
+     */
+    description: z.string().default('editing'),
+    heldBy: z.string().optional(),
+    participantKind: wireParticipantKindSchema.optional(),
+    position: z.number(),
+    expiresAt: z.number(),
+});
+/**
+ * The whole wait line for one row, rebroadcast to that row's peers on every
+ * queue mutation. This is what backs the reactive
+ * `ablo.<model>.claim.queue({ id })` read, which is why it carries the full
+ * line rather than a delta against it.
+ */
+export const claimQueueSchema = z.object({
+    target: streamTargetSchema.pick({ type: true, id: true }),
+    queue: z.array(claimQueueEntrySchema),
+});
+/**
+ * A held claim's TTL lapsed server-side. The claim is already inactive by the
+ * time this arrives, so a consumer either re-claims with a fresh credential or
+ * accepts the drop; there is nothing to release.
+ */
+export const claimExpiredSchema = z.object({
+    claimId: z.string(),
+});
+/**
+ * Why a claim ended without its holder releasing it, or was refused.
+ *
+ * A closed set, because the two refusals are different guarantees and a reader
+ * has to be able to tell them apart: `conflict` means someone holds the row
+ * right now and you may queue behind them, while `coordination_unavailable`
+ * means the coordinator could not answer, so nothing is known about the row.
+ * `expired` and `preempted` are the two ways a lease you held ends.
+ *
+ * The rejection frame's `reason` stays a plain string on the wire — it is
+ * frozen, and an older server may send a word not listed here. This is the
+ * reader's side of it: a value that parses becomes the typed reason, and one
+ * that does not is simply absent rather than smuggled through as prose.
+ * {@link claimExpiredSchema} and {@link claimLostSchema} already spelled their
+ * reasons as enums; this brings the refusals into line.
+ */
+export const claimEventReasonSchema = z.enum([
+    'conflict',
+    'coordination_unavailable',
+    'expired',
+    'preempted',
+]);
 /**
  * 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
@@ -324,38 +557,168 @@ export const modelTargetSchema = z
     path: z.string().optional(),
     range: targetRangeSchema.optional(),
     field: z.string().optional(),
+    /** Several named parts at once — see {@link targetRefSchema}. */
+    fields: z.array(z.string()).readonly().optional(),
     meta: z.record(z.string(), z.unknown()).optional(),
 })
     .readonly();
 /**
- * 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.
+ * The two states a claim can be observed in while it still exists.
  *
- * `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'`.
+ * Derived from {@link publicClaimStatusSchema} rather than spelled again: the
+ * other three are terminal and drop the claim from the observable set, so a
+ * listing or a peer's view can only ever see these. Extracting them by name
+ * means a state added to the public vocabulary is a deliberate decision about
+ * whether it is observable, not a silent omission.
  */
-export const modelClaimSchema = z
-    .object({
+export const heldClaimStatusSchema = publicClaimStatusSchema.extract([
+    'active',
+    'queued',
+]);
+/**
+ * ONE CLAIM — everything true about a lease at a moment: what it points at, who
+ * holds it, what they said they are doing, where it stands, and until when.
+ *
+ * Every caller-facing surface that answers a question about a claim is a
+ * PROJECTION of this record, never a second object: {@link modelClaimSchema} is
+ * what a peer may see, and `claimStateSchema` (`wire/claims.ts`) is what a
+ * caller polls about a claim of its own. Each is pinned to this record, so a
+ * field added here either reaches the people it was declared for or fails to
+ * compile.
+ *
+ * Before this, the peer-visible shape was a standalone `z.object` deriving from
+ * nothing, and the polling shape was a third. That is why it took reading four
+ * files to answer whether a heartbeat's progress reaches an asker — the
+ * declaring surface and the observing surface were kept in step by hand, and
+ * three of their shared fields had already drifted on how strictly they parse.
+ *
+ * What this record deliberately does NOT unify is the socket family
+ * ({@link wireClaimSchema} and its base). Those carry the same claim under the
+ * `entityType`/`entityId` locator rather than `model`/`id`, and they already
+ * derive from one another; collapsing the two locator spellings is a wire
+ * rename, not a projection.
+ */
+export const claimRecordSchema = z.object({
+    /** The claim's identity. Spelled `claimId` where a message names a claim it
+     *  is not itself, and `id` where the claim is the resource. */
     id: z.string(),
+    /** Who holds it. */
     actor: z.string(),
+    /** Parsed through {@link wireParticipantKindSchema}, so a legacy `'human'`
+     *  frame normalizes to `'user'`. */
     participantKind: wireParticipantKindSchema,
-    /** Peer-visible description of the work (`'rewriting the risk section'`).
-     *  Optional: a claim may be declared without one. */
-    description: z.string().optional(),
-    field: z.string().optional(),
-    status: z.enum(['active', 'queued']).optional(),
-    position: z.number().optional(),
-    expiresAt: z.number(),
-    /** The grant's fencing token (Option B), present on a claim you hold. */
-    fenceToken: z.number().optional(),
+    /**
+     * On whose authority the holder acts — the same three fields, with the same
+     * meanings, that `deltaAttributionSchema` records on every delta the claim
+     * goes on to produce, and sourced the same way: off the credential the
+     * connection authenticated with, never from the caller.
+     *
+     * A claim that carries only `actor` can say who is doing something and not
+     * who asked for it. "What is agent a7f3 doing" is a debugging question;
+     * "what is running on behalf of this customer right now" is an operations
+     * question, and until these are here it is answerable only in hindsight,
+     * against the audit log, after the fact.
+     *
+     * Null rather than absent when there is genuinely no delegator or no grant —
+     * a person acting directly is their own principal, and a session holds no
+     * capability.
+     */
+    onBehalfOfId: z.string().nullable(),
+    onBehalfOfKind: wireParticipantKindSchema.nullable(),
+    capabilityId: z.string().nullable(),
+    /**
+     * What the holder said they are doing (`'rewriting the risk section'`).
+     *
+     * A caller may declare it as `description`, as the older `reason`, or inside
+     * `meta`; {@link claimDescription} resolves those to this one field with a
+     * declared precedence, so only one of them is ever a shape.
+     */
+    description: z.string(),
+    /** Holding the row, or waiting in line for it. */
+    status: heldClaimStatusSchema,
+    /**
+     * Place in the wait line. Advisory: a privileged caller can reorder the
+     * queue, so a position can go UP between reads — only `status` is
+     * authoritative.
+     */
+    position: z.number().int().nonnegative(),
+    /**
+     * When the lease lapses without a heartbeat, in epoch milliseconds — 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.
+     */
+    expiresAt: z.number().int(),
+    /** The grant's fencing token, minted at acquisition. Present on a claim that
+     *  is held, never on one that is queued. */
+    fenceToken: z.number().int(),
+    /** The row, and which part of it. */
     target: modelTargetSchema,
+    /**
+     * The claim's metadata as an OPEN record — including what the coordinator
+     * writes there rather than the holder. A heartbeat's `details` lands here as
+     * `progress` (last beat wins), so an asker reads
+     * `claim.state({ id })?.meta.progress`. It is presence, not a checkpoint: it
+     * dies with the lease.
+     *
+     * This is the same bag the wire carries; what is new is that it has a home at
+     * the CLAIM level. Both projections used to file it under `target` alone, and
+     * `target.meta` is typed as the shape the program registered for its own claim
+     * metadata — so a server-written key was unreadable there by construction:
+     * `target.meta.progress` does not typecheck for any program that declared a
+     * shape, and the value was arriving in a slot whose type forbids it.
+     *
+     * Two views of one field, each typed for its reader: `target.meta` stays the
+     * holder's declared shape, and this stays open, because a peer reading someone
+     * else's claim has no grounds to assume the writer's declaration.
+     */
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * A claim as SDK callers and the HTTP claim routes see it
+ * (`ablo.<model>.claim.state`, `GET /v1/claims`) — the resolved, peer-readable
+ * view of one active or queued claim. The client's `ModelClaim` type derives
+ * from this shape.
+ *
+ * Everything but the deprecated `field` is projected from
+ * {@link claimRecordSchema}. Four members are optional here and required on the
+ * record, and the split is the same in each case: the record says what a claim
+ * IS, while a peer's view of one may legitimately have been built without them
+ * — a queued claim has no `fenceToken`, a held one has no `position`, an older
+ * producer sends no `status`, and a claim may be declared with no description.
+ */
+export const modelClaimSchema = claimRecordSchema
+    .partial({
+    description: true,
+    status: true,
+    position: true,
+    fenceToken: true,
+    // Additive: a server that predates the delegation trio omits all three,
+    // which is a different fact from a claim that has no delegator (null).
+    onBehalfOfId: true,
+    onBehalfOfKind: true,
+    capabilityId: true,
+})
+    .extend({
+    /**
+     * @deprecated Read `target.field` instead, and `target.fields` for a claim
+     * on several parts of the row. Removed in 0.36.0.
+     *
+     * This says the same thing as `target.field` and nothing keeps the two
+     * agreeing, so a producer that sets one and not the other publishes a
+     * claim that contradicts itself. It also cannot express a field set at
+     * all, which is the reason `target.fields` exists.
+     */
+    field: z.string().optional(),
 })
     .readonly();
+/**
+ * The peer-visible view covers the record. A field added to a claim is either
+ * projected to the people it was declared for, or deliberately dropped by an
+ * `.omit` here — never missing because nobody remembered the second object.
+ */
+const _modelClaimCoversRecord = true;
+void _modelClaimCoversRecord;
 /**
  * The `claim_begin` payload a client sends. It carries the descriptive target
  * and a `description` of the work, an optional duration hint, and the opt-in
@@ -548,19 +911,45 @@ export const commitOperationSchema = writeGuardSchema.extend({
 //  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). */
+/**
+ * What a participant is actively working on (agents fill this in).
+ *
+ * The two backpressure fields are part of the frame, not an extension of it:
+ * an agent worker announces them on every step, and an orchestrator reading
+ * peer activity routes work by them. They are declared here because a reader
+ * that validates this frame would otherwise drop them on the floor — the
+ * server passes both through without interpreting either.
+ */
 export const presenceActivitySchema = targetRefSchema.extend({
     action: z.string(),
     detail: z.string().optional(),
+    /** Backpressure signal in `[0, 1]`: `0` idle, `1` at capacity. */
+    loadFactor: z.number().optional(),
+    /** Gate for new assignments; absent means yes. */
+    acceptingNewWork: z.boolean().optional(),
 });
 /**
  * Full `presence_update` frame as the server broadcasts it. The activity +
  * `activeClaims` are the observation surface for the other two layers —
  * rendered, never acted on as enforcement.
+ *
+ * Open for the same reason {@link presenceUpdatePayloadSchema} is, and it has to
+ * be the same in both directions: whatever vocabulary an application announces
+ * through presence, it reads back off its peers' frames. A reader that parsed
+ * this strictly would validate the frame and quietly discard the part the
+ * application actually came for.
  */
-export const presenceUpdateFrameSchema = z.object({
+export const presenceUpdateSchema = z.object({
     kind: presenceKindSchema,
-    userId: z.string().optional(),
+    /**
+     * Who the frame is about. Required, because every one of the five sites that
+     * builds a presence frame stamps it from the connection's identity — an
+     * anonymous presence frame has never been sent and would say nothing. It was
+     * optional here for as long as nothing parsed the frame, and the hand-written
+     * copy the transport used to carry declared it required; two descriptions of
+     * one frame can disagree indefinitely while neither is ever checked.
+     */
+    userId: z.string(),
     syncGroups: z.array(z.string()).optional(),
     timestamp: z.number().optional(),
     status: z.string(),
@@ -575,4 +964,50 @@ export const presenceUpdateFrameSchema = z.object({
     participantKind: wireParticipantKindSchema.optional(),
     activeClaims: z.array(wireClaimSchema).optional(),
     delegatedFrom: z.string().nullish(),
-});
+}).catchall(z.unknown());
+/**
+ * @deprecated Renamed to {@link presenceUpdateSchema}. Removed in 0.36.0.
+ *
+ * `Frame` was the only such suffix in this vocabulary: every other frame the
+ * server sends is named plainly — {@link claimLostSchema},
+ * {@link claimAcquiredSchema}, {@link claimRejectionSchema} — and the client's
+ * half carries `Payload`. One name did not follow the rule the other fifteen do.
+ */
+export const presenceUpdateFrameSchema = presenceUpdateSchema;
+/**
+ * The `presence_update` payload a client SENDS — deliberately much smaller
+ * than the frame the server broadcasts back.
+ *
+ * Everything that identifies or situates the participant is stamped by the
+ * server and cannot be declared here: `userId`, `participantKind`, `isAgent`,
+ * `syncGroups`, `timestamp`, `kind`, and `delegatedFrom` all come from the
+ * connection's own identity. A client that sends them is not believed — an
+ * older SDK once hardcoded `isAgent: true` on every announce, and because the
+ * payload was spread into the broadcast unfiltered, every human session
+ * rendered to its peers as an agent. Parsing an inbound payload through this
+ * schema and broadcasting the *result* is what makes that structurally
+ * impossible rather than a rule the broadcast has to remember.
+ *
+ * `status` is a plain string, matching the outbound frame: the three canonical
+ * values are conventions the presence UI understands, not a closed set the
+ * protocol enforces.
+ *
+ * The payload is deliberately OPEN — `catchall` keeps keys this schema does not
+ * name. Presence is the one frame an application extends: an agent mesh
+ * announces its own coordination vocabulary through it and reads it back off
+ * peer frames, without the protocol having to learn each app's words. So the
+ * fields named here are validated and typed, and anything else rides along
+ * untouched. Openness is not the same as trust: the server-stamped identity
+ * fields are applied AFTER this payload is spread into the broadcast, so a
+ * client that sends its own `userId` or `isAgent` is overwritten either way.
+ */
+export const presenceUpdatePayloadSchema = z
+    .object({
+    status: z.string().optional(),
+    activity: presenceActivitySchema.optional(),
+    /** The sender's own open claims, which replace what the server holds. */
+    activeClaims: z.array(wireClaimSchema).optional(),
+    timezone: z.string().optional(),
+    customStatus: z.string().optional(),
+})
+    .catchall(z.unknown());