@abloatai/ablo 0.10.0 → 0.11.0

package/dist/coordination/schema.js

@@ -1,4 +1,5 @@
 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.
@@ -6,7 +7,7 @@ import { z } from 'zod';
  * one decision") for the conceptual model. The layers, outer-to-inner:
  *
  *   1. PRESENCE       (observation)    — who is working where; NEVER enforces.
- *   2. PESSIMISTIC    (claims/leases)  — `intent_begin`/`intent_abandon`;
+ *   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.
@@ -14,8 +15,8 @@ import { z } from 'zod';
  * 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 intent view dropping
- * `status`/`error`, `onStale` declared 5×, `IntentStatus` declared 2× — into
+ * 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.
  */
 // ─────────────────────────────────────────────────────────────────────────
@@ -30,7 +31,39 @@ export const targetRangeSchema = z.object({
 });
 export const participantKindSchema = z.enum(['user', 'agent', 'system']);
 /**
- * What a claim / intent / activity points at. The common locator shared by
+ * 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.
+ */
+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).
+ */
+export function participantKindFromWire(wireKind, isAgent) {
+    const parsed = wireParticipantKindSchema.safeParse(wireKind);
+    if (parsed.success)
+        return parsed.data;
+    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`).
+ */
+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.
  */
@@ -64,34 +97,58 @@ export const writeGuardSchema = z.object({
     bypass: z.boolean().optional(),
 });
 // ─────────────────────────────────────────────────────────────────────────
-//  Layer 2 — PESSIMISTIC claim / intent-lease
+//  Layer 2 — PESSIMISTIC claim / claim-lease
 // ─────────────────────────────────────────────────────────────────────────
 /**
- * Lifecycle of an intent — the Stripe `PaymentIntent.status` shape. Absent on
+ * Lifecycle of an claim — the Stripe `PaymentIntent.status` shape. Absent on
  * the wire ⇒ `'active'` (additive back-compat). The server stamps `'active'`
- * on `intent_begin` and emits a single terminal frame (`committed` /
+ * 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.
  */
-export const intentStatusSchema = z.enum([
+export const claimStatusSchema = z.enum([
     'active',
     'committed',
     'expired',
     'canceled',
 ]);
+const wireClaimBaseSchema = targetRefSchema.extend({
+    claimId: z.string(),
+    /** Verb the agent expects: 'update' | 'create' | 'editing' | 'reviewing' … */
+    action: z.string(),
+    /** Server-stamped declaration time (epoch ms). */
+    declaredAt: z.number(),
+    /** Server-computed TTL deadline (epoch ms). Readers treat as advisory. */
+    expiresAt: z.number(),
+    status: claimStatusSchema.optional(),
+});
+export const wireClaimSummarySchema = wireClaimBaseSchema.pick({
+    claimId: true,
+    action: true,
+    declaredAt: true,
+    expiresAt: true,
+    entityType: true,
+    entityId: true,
+    field: true,
+    meta: true,
+});
 /** Why a claim ended in a non-success terminal state. */
-export const intentErrorSchema = z.object({
+export const claimErrorSchema = z.object({
     code: z.string(),
     message: z.string().optional(),
     /** Participant already holding the target (conflict rejections). */
     heldBy: z.string().optional(),
-    heldByIntentId: z.string().optional(),
+    heldByClaimId: z.string().optional(),
     heldByExpiresAt: z.number().optional(),
+    /** Rich holder context for conflict rejections. Additive: older frames omit it. */
+    heldByClaim: wireClaimSummarySchema.optional(),
+    /** Optional conflict-policy explanation. Additive: older frames omit it. */
+    policyReason: z.string().optional(),
 });
 /**
- * A declared pending-mutation intent — the unit broadcast in presence
- * `activeIntents`. Clients supply the descriptive `targetRef` fields, an
- * `action`, and a chosen `intentId`; the SERVER stamps `declaredAt` /
+ * A declared pending-mutation claim — the unit broadcast in presence
+ * `activeClaims`. Clients supply the descriptive `targetRef` fields, an
+ * `action`, 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
@@ -100,61 +157,132 @@ export const intentErrorSchema = z.object({
  * was used, so the two prior copies collapse into this one without breaking
  * SDK consumers.
  */
-export const intentClaimSchema = targetRefSchema.extend({
-    intentId: z.string(),
-    /** Verb the agent expects: 'update' | 'create' | 'editing' | 'reviewing' … */
+export const wireClaimSchema = wireClaimBaseSchema.extend({
+    error: claimErrorSchema.optional(),
+});
+export const claimRejectionSchema = z.object({
+    claimId: z.string(),
+    reason: z.string(),
+    target: targetRefSchema.optional(),
+    heldBy: z.string().optional(),
+    heldByClaimId: z.string().optional(),
+    heldByExpiresAt: z.number().optional(),
+    heldByClaim: wireClaimSummarySchema.optional(),
+    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`.
+ */
+export const modelTargetSchema = z
+    .object({
+    model: z.string(),
+    id: z.string(),
+    path: z.string().optional(),
+    range: targetRangeSchema.optional(),
+    field: z.string().optional(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+})
+    .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.
+ *
+ * `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'`.
+ */
+export const modelClaimSchema = z
+    .object({
+    id: z.string(),
+    actor: z.string(),
+    participantKind: wireParticipantKindSchema,
     action: z.string(),
-    /** Server-stamped declaration time (epoch ms). */
-    declaredAt: z.number(),
-    /** Server-computed TTL deadline (epoch ms). Readers treat as advisory. */
+    description: z.string().optional(),
+    field: z.string().optional(),
+    status: z.enum(['active', 'queued']).optional(),
+    position: z.number().optional(),
     expiresAt: z.number(),
-    status: intentStatusSchema.optional(),
-    error: intentErrorSchema.optional(),
-});
+    target: modelTargetSchema,
+})
+    .readonly();
 /**
- * `intent_begin` payload (client → server). The descriptive target + action,
+ * `claim_begin` payload (client → server). The descriptive target + action,
  * 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.
  */
-export const intentBeginPayloadSchema = targetRefSchema.extend({
-    intentId: z.string(),
+export const claimBeginPayloadSchema = targetRefSchema.extend({
+    claimId: z.string(),
     action: z.string(),
     /** 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 `intent_queued` → later
-     * `intent_granted`, instead of `intent_rejected`. Clients that set this MUST
+     * enqueues this claim (FIFO) and replies `claim_queued` → later
+     * `claim_granted`, instead of `claim_rejected`. Clients that set this MUST
      * handle the grant.
      */
     queue: z.boolean().optional(),
 });
 /**
- * `intent_abandon` payload (client → server). `entityType`/`entityId` are
- * carried so the server can DEQUEUE a still-*waiting* (not held) intent from
- * the FIFO line — the held-intent path needs only `intentId`. (The previous
+ * `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.)
  */
-export const intentAbandonPayloadSchema = z.object({
-    intentId: z.string(),
+export const claimAbandonPayloadSchema = z.object({
+    claimId: z.string(),
     entityType: z.string().optional(),
     entityId: z.string().optional(),
 });
 /**
- * `intent_reorder` payload (client → server). A privileged participant (e.g. a
+ * `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`+`intentId` in the desired priority. Waiters
+ * `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 `intent_abandon`
+ * 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.
  */
-export const intentReorderPayloadSchema = z.object({
+export const claimReorderPayloadSchema = z.object({
     entityType: z.string(),
     entityId: z.string(),
-    order: z.array(z.object({ heldBy: z.string(), intentId: z.string() })),
+    order: z.array(z.object({ heldBy: z.string(), claimId: z.string() })),
+});
+// ─────────────────────────────────────────────────────────────────────────
+//  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
+ * {@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.
+ */
+export const updateSubscriptionPayloadSchema = z.object({
+    syncGroups: z.array(syncGroupInputSchema),
+});
+/**
+ * `subscription_ack` payload (server → client). Echoes the connection's
+ * effective read set after the update (unchanged on rejection — the update is
+ * atomic). `error` is present iff `success` is false (e.g. a scoped key
+ * requesting a group outside its grant). `syncGroups` is lenient
+ * (`z.string()`) here, not branded: it is the server's own echo for display,
+ * not untrusted input, and includes base anchors like `org:<id>`.
+ */
+export const subscriptionAckPayloadSchema = z.object({
+    success: z.boolean(),
+    syncGroups: z.array(z.string()),
+    error: z.object({ code: z.string(), message: z.string() }).optional(),
 });
 // ─────────────────────────────────────────────────────────────────────────
 //  Commit operation — carries the optimistic write-guard (Layer 3)
@@ -191,7 +319,7 @@ export const presenceActivitySchema = targetRefSchema.extend({
 });
 /**
  * Full `presence_update` frame as the server broadcasts it. The activity +
- * `activeIntents` are the observation surface for the other two layers —
+ * `activeClaims` are the observation surface for the other two layers —
  * rendered, never acted on as enforcement.
  */
 export const presenceUpdateFrameSchema = z.object({
@@ -204,6 +332,11 @@ export const presenceUpdateFrameSchema = z.object({
     customStatus: z.string().optional(),
     activity: presenceActivitySchema.optional(),
     isAgent: z.boolean().optional(),
-    activeIntents: z.array(intentClaimSchema).optional(),
+    /**
+     * Server-stamped canonical kind. Additive — older servers omit it and
+     * readers fall back to `isAgent` (see {@link participantKindFromWire}).
+     */
+    participantKind: wireParticipantKindSchema.optional(),
+    activeClaims: z.array(wireClaimSchema).optional(),
     delegatedFrom: z.string().nullish(),
 });

package/dist/core/index.d.ts

@@ -23,6 +23,6 @@ export { computeFKDepthPriority, type InternalAbloOptions } from '../client/Ablo
 export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
 export { SyncWebSocket, type SyncDelta, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
 export { BootstrapHelper } from '../sync/BootstrapHelper.js';
-export { createIntentStream, type AttachableIntentStream, type IntentStreamConfig, } from '../sync/createIntentStream.js';
-export { awaitIntentGrant, type GrantTransport, } from '../sync/awaitIntentGrant.js';
+export { createClaimStream, type AttachableClaimStream, type ClaimStreamConfig, } from '../sync/createClaimStream.js';
+export { awaitClaimGrant, type GrantTransport, } from '../sync/awaitClaimGrant.js';
 export { LoadStrategy } from '../types/index.js';

package/dist/core/index.js

@@ -30,13 +30,13 @@ export { computeFKDepthPriority } from '../client/Ablo.js';
 // multi-agent demo harnesses.
 export { SyncWebSocket, } from '../sync/SyncWebSocket.js';
 export { BootstrapHelper } from '../sync/BootstrapHelper.js';
-// Intent coordination primitives (the lower-level pieces behind the
+// Claim coordination primitives (the lower-level pieces behind the
 // consumer-facing `ablo.<model>.claim`). The stream factory builds the
-// announce/await machinery on a SyncWebSocket; `awaitIntentGrant` is the
+// announce/await machinery on a SyncWebSocket; `awaitClaimGrant` is the
 // fair-queue grant coordinator. Exposed on /core for framework-level
 // orchestration and e2e harnesses — NOT on the consumer `.` root.
-export { createIntentStream, } from '../sync/createIntentStream.js';
-export { awaitIntentGrant, } from '../sync/awaitIntentGrant.js';
+export { createClaimStream, } from '../sync/createClaimStream.js';
+export { awaitClaimGrant, } from '../sync/awaitClaimGrant.js';
 // Schema/model load strategy enum — referenced by model registration in
 // framework code.
 export { LoadStrategy } from '../types/index.js';

package/dist/errorCodes.d.ts

@@ -37,9 +37,9 @@ import { z } from 'zod';
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export declare const ERROR_CONTRACT_VERSION = "2026-06-02";
+export declare const ERROR_CONTRACT_VERSION = "2026-06-13";
 /** Coarse grouping for metrics dashboards and docs sectioning. */
-export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'intent' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
+export type ErrorCategory = 'auth' | 'permission' | 'capability' | 'claim' | 'conflict' | 'validation' | 'not_found' | 'tenant' | 'schema' | 'claim' | 'bootstrap' | 'transport' | 'rate_limit' | 'server' | 'client';
 /**
  * The closed taxonomy of *how a failure recovers* — one rung above the raw
  * `code`. Where `code` says **what** went wrong, `RecoveryClass` says **what
@@ -151,8 +151,8 @@ export declare const ERROR_CODES: {
     readonly claim_conflict: ErrorCodeSpec;
     readonly claim_lost: ErrorCodeSpec;
     readonly entity_claimed: ErrorCodeSpec;
-    readonly intent_conflict: ErrorCodeSpec;
     readonly malformed_claim: ErrorCodeSpec;
+    readonly malformed_subscription: ErrorCodeSpec;
     readonly model_claimed: ErrorCodeSpec;
     readonly model_claimed_timeout: ErrorCodeSpec;
     readonly model_claim_not_configured: ErrorCodeSpec;
@@ -207,11 +207,11 @@ export declare const ERROR_CODES: {
     readonly required_field_added: ErrorCodeSpec;
     readonly enum_value_removed: ErrorCodeSpec;
     readonly risky_cast: ErrorCodeSpec;
-    readonly intent_lease_unavailable: ErrorCodeSpec;
-    readonly intent_not_wired: ErrorCodeSpec;
-    readonly intent_queued: ErrorCodeSpec;
-    readonly intent_wait_aborted: ErrorCodeSpec;
-    readonly intent_wait_poll_interval_required: ErrorCodeSpec;
+    readonly claim_lease_unavailable: ErrorCodeSpec;
+    readonly claim_not_wired: ErrorCodeSpec;
+    readonly claim_queued: ErrorCodeSpec;
+    readonly claim_wait_aborted: ErrorCodeSpec;
+    readonly claim_wait_poll_interval_required: ErrorCodeSpec;
     readonly grant_timeout: ErrorCodeSpec;
     readonly slide_intent_missing_deck_id: ErrorCodeSpec;
     readonly slide_intent_unknown_sibling: ErrorCodeSpec;
@@ -311,7 +311,7 @@ export declare const ERROR_CODES: {
     readonly upload_items_required: ErrorCodeSpec;
     readonly presigned_url_failed: ErrorCodeSpec;
     readonly task_id_required: ErrorCodeSpec;
-    readonly intent_id_required: ErrorCodeSpec;
+    readonly claim_id_required: ErrorCodeSpec;
     readonly commit_operation_action_required: ErrorCodeSpec;
     readonly commit_operation_unsupported: ErrorCodeSpec;
     readonly usage_invalid: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -37,7 +37,7 @@ import { z } from 'zod';
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export const ERROR_CONTRACT_VERSION = '2026-06-02';
+export const ERROR_CONTRACT_VERSION = '2026-06-13';
 /**
  * The closed taxonomy of *how a failure recovers* — one rung above the raw
  * `code`. Where `code` says **what** went wrong, `RecoveryClass` says **what
@@ -141,7 +141,7 @@ export const ERROR_CODES = {
     byo_role_unreadable: wire('permission', 403, false, 'The direct Postgres connector role could not be introspected.'),
     byo_tenant_tables_unforced_rls: wire('permission', 403, false, 'Tenant tables do not have RLS forced under the direct Postgres connector role.'),
     byo_host_not_allowed: wire('permission', 403, false, 'The direct Postgres connector host resolves to a private, loopback, or link-local address and cannot be used.'),
-    // ── claim / intent conflict (409) ──────────────────────────────────
+    // ── claim / claim conflict (409) ──────────────────────────────────
     // Held-claim rejections are NOT queue-retryable (gRPC FAILED_PRECONDITION /
     // ABORTED semantics; Replicache/Zero SETTLE a rejected mutation — reject the
     // caller, roll back the optimistic effect — instead of resending it).
@@ -154,8 +154,8 @@ export const ERROR_CODES = {
     claim_conflict: wire('claim', 409, false, 'The target entity is claimed by another participant.'),
     claim_lost: wire('claim', 409, false, 'A previously held claim was lost before the write applied.'),
     entity_claimed: wire('claim', 409, false, 'The target entity is currently claimed; write was blocked.'),
-    intent_conflict: wire('claim', 409, false, 'An intent on the target conflicts with an active intent (server-internal alias of claim_conflict).'),
     malformed_claim: wire('claim', 400, false, 'The claim payload was malformed.'),
+    malformed_subscription: wire('validation', 400, false, 'The update_subscription payload was malformed; expected { syncGroups: string[] }.'),
     model_claimed: wire('claim', 409, false, 'The model instance is claimed by another participant.'),
     model_claimed_timeout: wire('claim', 409, false, 'Timed out waiting for a model claim to clear.'),
     model_claim_not_configured: client('claim', 'Claiming was requested on a model that has no claim configuration.'),
@@ -164,7 +164,7 @@ export const ERROR_CODES = {
     idempotency_conflict: wire('conflict', 409, false, 'The same Idempotency-Key was reused with a different request body.'),
     idempotency_key_too_long: wire('validation', 400, false, 'The supplied Idempotency-Key exceeds the maximum length.'),
     // ── validation (400 / 422) ─────────────────────────────────────────
-    write_options_invalid: client('validation', 'The write options (`idempotencyKey` / `label` / `wait` / `readAt` / `onStale` / `intent`) failed validation against the write-options schema.'),
+    write_options_invalid: client('validation', 'The write options (`idempotencyKey` / `label` / `wait` / `readAt` / `onStale` / `claim`) failed validation against the write-options schema.'),
     source_operation_id_required: client('validation', 'A data-source operation arrived without the entity `id` it targets.'),
     source_adapter_misconfigured: client('validation', 'The data-source ORM adapter could not map a schema model onto the backing client (missing delegate or model).'),
     source_event_invalid: client('validation', 'A data-source outbox event could not be built — the operation carries no entity id and none was supplied.'),
@@ -222,15 +222,15 @@ export const ERROR_CODES = {
     required_field_added: client('schema', 'Migration adds a new required field.'),
     enum_value_removed: client('schema', 'Migration removes an enum value (destructive classification).'),
     risky_cast: client('schema', 'Migration would perform a risky column type cast.'),
-    // ── intent / lease (409 / transport) ───────────────────────────────
-    intent_lease_unavailable: wire('intent', 503, true, 'The intent-lease coordination subsystem is unavailable; retry.'),
-    intent_not_wired: client('intent', 'Intent support was used but is not wired in this runtime.'),
-    intent_queued: wire('intent', 409, true, 'The intent was queued behind an active lease holder.'),
-    intent_wait_aborted: wire('intent', 409, true, 'Waiting for the intent lease was aborted.'),
-    intent_wait_poll_interval_required: client('intent', 'A poll interval is required when waiting on an intent.'),
-    grant_timeout: wire('intent', 504, true, 'Timed out waiting for a capability grant.'),
-    slide_intent_missing_deck_id: wire('intent', 400, false, 'A slide intent was missing its deck id.'),
-    slide_intent_unknown_sibling: wire('intent', 400, false, 'A slide intent referenced an unknown sibling slide.'),
+    // ── claim / lease (409 / transport) ───────────────────────────────
+    claim_lease_unavailable: wire('claim', 503, true, 'The claim-lease coordination subsystem is unavailable; retry.'),
+    claim_not_wired: client('claim', 'Claim support was used but is not wired in this runtime.'),
+    claim_queued: wire('claim', 409, true, 'The claim was queued behind an active lease holder.'),
+    claim_wait_aborted: wire('claim', 409, true, 'Waiting for the claim lease was aborted.'),
+    claim_wait_poll_interval_required: client('claim', 'A poll interval is required when waiting on an claim.'),
+    grant_timeout: wire('claim', 504, true, 'Timed out waiting for a capability grant.'),
+    slide_intent_missing_deck_id: wire('claim', 400, false, 'A slide claim was missing its deck id.'),
+    slide_intent_unknown_sibling: wire('claim', 400, false, 'A slide claim referenced an unknown sibling slide.'),
     // ── bootstrap (transport) ──────────────────────────────────────────
     bootstrap_fetch_timeout: wire('bootstrap', 504, true, 'The bootstrap fetch timed out.'),
     bootstrap_offline: wire('bootstrap', 503, true, 'Bootstrap could not run because the client is offline.'),
@@ -333,7 +333,7 @@ export const ERROR_CODES = {
     upload_items_required: wire('validation', 400, false, 'The request must include a non-empty items array.'),
     presigned_url_failed: wire('server', 500, true, 'Failed to generate a presigned upload URL.'),
     task_id_required: wire('validation', 400, false, 'A task id is required for this request.'),
-    intent_id_required: wire('validation', 400, false, 'An intent id is required for this request.'),
+    claim_id_required: wire('validation', 400, false, 'An claim id is required for this request.'),
     commit_operation_action_required: wire('validation', 400, false, 'A commit operation is missing its `action`.'),
     commit_operation_unsupported: wire('validation', 400, false, 'A commit operation used an unsupported `action`.'),
     usage_invalid: wire('validation', 400, false, 'The usage request was invalid.'),
@@ -348,7 +348,7 @@ export const ERROR_CODES = {
     parent_turn_foreign_agent: wire('permission', 403, false, 'The parent turn belongs to a different agent.'),
     turn_not_found: wire('not_found', 404, false, 'The referenced turn does not exist.'),
     turn_foreign_agent: wire('permission', 403, false, 'The turn belongs to a different agent.'),
-    invalid_intent: wire('validation', 400, false, 'The intent request was invalid.'),
+    invalid_intent: wire('validation', 400, false, 'The claim request was invalid.'),
     schema_too_large: wire('validation', 413, false, 'The submitted schema exceeds the maximum size.'),
     invalid_schema: wire('validation', 400, false, 'The submitted schema could not be parsed.'),
     incompatible_change: wire('conflict', 409, false, 'The schema change is incompatible with the current schema.'),

package/dist/errors.d.ts

@@ -19,6 +19,7 @@
  * Both work on every subclass.
  */
 import type { ErrorCode } from './errorCodes.js';
+import { type WireClaimSummary, type ModelClaim, type ModelTarget, type ParticipantKind } from './coordination/schema.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errorCodes.js';
 export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errorCodes.js';
 /** Common shape for all errors thrown by this SDK. */
@@ -155,6 +156,32 @@ export declare class AbloStaleContextError extends AbloError {
         }>;
     });
 }
+export interface ClaimContext {
+    readonly id?: string;
+    readonly claimId?: string;
+    readonly actor?: string;
+    readonly participantKind?: ParticipantKind;
+    readonly action?: string;
+    readonly description?: string;
+    readonly field?: string;
+    readonly status?: string;
+    readonly position?: number;
+    /** Epoch-ms the claim expires. One timestamp encoding everywhere. */
+    readonly expiresAt?: number;
+    readonly declaredAt?: number;
+    readonly entityType?: string;
+    readonly entityId?: string;
+    readonly target?: Partial<ModelTarget>;
+    readonly meta?: Record<string, unknown>;
+}
+export type ClaimErrorClaim = WireClaimSummary | ClaimContext;
+export declare function formatClaimedErrorMessage(args: {
+    readonly targetLabel: string;
+    readonly heldBy?: string;
+    readonly claim?: ClaimErrorClaim;
+    readonly policyReason?: string;
+    readonly fallback?: string;
+}): string;
 /**
  * The target entity is currently claimed by another participant and the caller
  * asked the SDK not to read/write through that claim.
@@ -164,15 +191,36 @@ export declare class AbloStaleContextError extends AbloError {
  */
 export declare class AbloClaimedError extends AbloError {
     readonly type: "AbloClaimedError";
-    readonly claims?: ReadonlyArray<unknown>;
+    readonly claims?: ReadonlyArray<ClaimErrorClaim>;
     constructor(message: string, options?: {
         code?: ErrorCode;
         httpStatus?: number;
         requestId?: string;
         cause?: unknown;
-        claims?: ReadonlyArray<unknown>;
+        claims?: ReadonlyArray<ClaimErrorClaim>;
     });
 }
+/**
+ * The `/`-joined human label for a claim target — `model/id/field`, dropping
+ * absent parts, falling back to `'target'`. The one place this join lived in
+ * three copies (client `Ablo`, HTTP `ApiClient`, `awaitClaimGrant`).
+ */
+export declare function claimTargetLabel(target: {
+    readonly model?: string;
+    readonly id?: string;
+    readonly field?: string;
+}): string;
+/**
+ * Build the {@link AbloClaimedError} for a contended `ablo.<model>` write — the
+ * single factory shared by the realtime client (`Ablo`) and the HTTP client
+ * (`ApiClient`), which carried byte-identical copies. The first claim is the
+ * holder whose metadata shapes the message.
+ */
+export declare function claimedError(target: {
+    readonly model?: string;
+    readonly id?: string;
+    readonly field?: string;
+}, claims: readonly ModelClaim[], code: 'model_claimed' | 'model_claimed_timeout' | 'queue_too_deep'): AbloClaimedError;
 /**
  * Structured description of the capability an agent would need to
  * satisfy a denied request. Mirrors the x402 `paymentRequirements`
@@ -304,6 +352,7 @@ export declare function errorFromWire(message: string, opts?: {
     httpStatus?: number;
     requestId?: string;
     requiredCapability?: RequiredCapability;
+    claims?: ReadonlyArray<ClaimErrorClaim>;
 }): AbloError;
 /**
  * Translate an HTTP response into the appropriate typed error.