@abloatai/ablo 0.10.0 → 0.11.0

package/dist/coordination/schema.d.ts

@@ -6,7 +6,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 +14,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.
  */
 /** A line/column span within a text-bearing field (slide body, doc, cell). */
@@ -33,7 +33,36 @@ export declare const participantKindSchema: z.ZodEnum<{
 }>;
 export type ParticipantKind = z.infer<typeof participantKindSchema>;
 /**
- * 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 declare const wireParticipantKindSchema: z.ZodPreprocess<z.ZodEnum<{
+    user: "user";
+    agent: "agent";
+    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).
+ */
+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`).
+ */
+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.
  */
@@ -82,32 +111,54 @@ export declare const writeGuardSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type WriteGuard = z.infer<typeof writeGuardSchema>;
 /**
- * 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 declare const intentStatusSchema: z.ZodEnum<{
+export declare const claimStatusSchema: z.ZodEnum<{
     active: "active";
     committed: "committed";
     expired: "expired";
     canceled: "canceled";
 }>;
-export type IntentStatus = z.infer<typeof intentStatusSchema>;
+export type ClaimStatus = z.infer<typeof claimStatusSchema>;
+export declare const wireClaimSummarySchema: z.ZodObject<{
+    field: z.ZodOptional<z.ZodString>;
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    claimId: z.ZodString;
+    action: z.ZodString;
+    declaredAt: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+export type WireClaimSummary = z.infer<typeof wireClaimSummarySchema>;
 /** Why a claim ended in a non-success terminal state. */
-export declare const intentErrorSchema: z.ZodObject<{
+export declare const claimErrorSchema: z.ZodObject<{
     code: z.ZodString;
     message: z.ZodOptional<z.ZodString>;
     heldBy: z.ZodOptional<z.ZodString>;
-    heldByIntentId: z.ZodOptional<z.ZodString>;
+    heldByClaimId: z.ZodOptional<z.ZodString>;
     heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+    heldByClaim: z.ZodOptional<z.ZodObject<{
+        field: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        claimId: z.ZodString;
+        action: z.ZodString;
+        declaredAt: z.ZodNumber;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strip>>;
+    policyReason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type IntentError = z.infer<typeof intentErrorSchema>;
+export type ClaimError = z.infer<typeof claimErrorSchema>;
 /**
- * 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
@@ -116,7 +167,7 @@ export type IntentError = z.infer<typeof intentErrorSchema>;
  * was used, so the two prior copies collapse into this one without breaking
  * SDK consumers.
  */
-export declare const intentClaimSchema: z.ZodObject<{
+export declare const wireClaimSchema: z.ZodObject<{
     entityType: z.ZodString;
     entityId: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
@@ -128,7 +179,7 @@ export declare const intentClaimSchema: z.ZodObject<{
     }, z.core.$strip>>;
     field: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    intentId: z.ZodString;
+    claimId: z.ZodString;
     action: z.ZodString;
     declaredAt: z.ZodNumber;
     expiresAt: z.ZodNumber;
@@ -142,18 +193,125 @@ export declare const intentClaimSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodOptional<z.ZodString>;
         heldBy: z.ZodOptional<z.ZodString>;
-        heldByIntentId: z.ZodOptional<z.ZodString>;
+        heldByClaimId: z.ZodOptional<z.ZodString>;
         heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+        heldByClaim: z.ZodOptional<z.ZodObject<{
+            field: z.ZodOptional<z.ZodString>;
+            entityType: z.ZodString;
+            entityId: z.ZodString;
+            meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            claimId: z.ZodString;
+            action: z.ZodString;
+            declaredAt: z.ZodNumber;
+            expiresAt: z.ZodNumber;
+        }, z.core.$strip>>;
+        policyReason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export type IntentClaim = z.infer<typeof intentClaimSchema>;
+export type WireClaim = z.infer<typeof wireClaimSchema>;
+export declare const claimRejectionSchema: z.ZodObject<{
+    claimId: z.ZodString;
+    reason: z.ZodString;
+    target: z.ZodOptional<z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        range: z.ZodOptional<z.ZodObject<{
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+            startColumn: z.ZodOptional<z.ZodNumber>;
+            endColumn: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        field: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    heldBy: z.ZodOptional<z.ZodString>;
+    heldByClaimId: z.ZodOptional<z.ZodString>;
+    heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+    heldByClaim: z.ZodOptional<z.ZodObject<{
+        field: z.ZodOptional<z.ZodString>;
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        claimId: z.ZodString;
+        action: z.ZodString;
+        declaredAt: z.ZodNumber;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strip>>;
+    policyReason: z.ZodOptional<z.ZodString>;
+}, 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`.
+ */
+export declare const modelTargetSchema: z.ZodReadonly<z.ZodObject<{
+    model: z.ZodString;
+    id: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodObject<{
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        startColumn: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    field: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, 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.
+ *
+ * `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 declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
+    id: z.ZodString;
+    actor: z.ZodString;
+    participantKind: z.ZodPreprocess<z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>>;
+    action: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    field: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        queued: "queued";
+    }>>;
+    position: z.ZodOptional<z.ZodNumber>;
+    expiresAt: z.ZodNumber;
+    target: z.ZodReadonly<z.ZodObject<{
+        model: z.ZodString;
+        id: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        range: z.ZodOptional<z.ZodObject<{
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+            startColumn: z.ZodOptional<z.ZodNumber>;
+            endColumn: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        field: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export type ModelClaim = z.infer<typeof modelClaimSchema>;
 /**
- * `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 declare const intentBeginPayloadSchema: z.ZodObject<{
+export declare const claimBeginPayloadSchema: z.ZodObject<{
     entityType: z.ZodString;
     entityId: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
@@ -165,43 +323,72 @@ export declare const intentBeginPayloadSchema: z.ZodObject<{
     }, z.core.$strip>>;
     field: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    intentId: z.ZodString;
+    claimId: z.ZodString;
     action: z.ZodString;
     estimatedMs: z.ZodOptional<z.ZodNumber>;
     queue: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
-export type IntentBeginPayload = z.infer<typeof intentBeginPayloadSchema>;
+export type ClaimBeginPayload = z.infer<typeof claimBeginPayloadSchema>;
 /**
- * `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 declare const intentAbandonPayloadSchema: z.ZodObject<{
-    intentId: z.ZodString;
+export declare const claimAbandonPayloadSchema: z.ZodObject<{
+    claimId: z.ZodString;
     entityType: z.ZodOptional<z.ZodString>;
     entityId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type IntentAbandonPayload = z.infer<typeof intentAbandonPayloadSchema>;
+export type ClaimAbandonPayload = z.infer<typeof claimAbandonPayloadSchema>;
 /**
- * `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 declare const intentReorderPayloadSchema: z.ZodObject<{
+export declare const claimReorderPayloadSchema: z.ZodObject<{
     entityType: z.ZodString;
     entityId: z.ZodString;
     order: z.ZodArray<z.ZodObject<{
         heldBy: z.ZodString;
-        intentId: z.ZodString;
+        claimId: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export type IntentReorderPayload = z.infer<typeof intentReorderPayloadSchema>;
+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
+ * {@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 declare const updateSubscriptionPayloadSchema: z.ZodObject<{
+    syncGroups: z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"default">, z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">]>>;
+}, z.core.$strip>;
+export type UpdateSubscriptionPayload = z.infer<typeof updateSubscriptionPayloadSchema>;
+/**
+ * `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 declare const subscriptionAckPayloadSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    syncGroups: z.ZodArray<z.ZodString>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SubscriptionAckPayload = z.infer<typeof subscriptionAckPayloadSchema>;
 export declare const commitOperationTypeSchema: z.ZodEnum<{
     CREATE: "CREATE";
     UPDATE: "UPDATE";
@@ -238,6 +425,14 @@ export declare const commitOperationSchema: z.ZodObject<{
     transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, 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.
+ */
+export type AnyCommitOperation = CommitOperation;
 export declare const presenceKindSchema: z.ZodEnum<{
     enter: "enter";
     update: "update";
@@ -263,7 +458,7 @@ export declare const presenceActivitySchema: z.ZodObject<{
 export type PresenceActivity = z.infer<typeof presenceActivitySchema>;
 /**
  * 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 declare const presenceUpdateFrameSchema: z.ZodObject<{
@@ -294,7 +489,12 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
         detail: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     isAgent: z.ZodOptional<z.ZodBoolean>;
-    activeIntents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    participantKind: z.ZodOptional<z.ZodPreprocess<z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>>>;
+    activeClaims: z.ZodOptional<z.ZodArray<z.ZodObject<{
         entityType: z.ZodString;
         entityId: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
@@ -306,7 +506,7 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
         }, z.core.$strip>>;
         field: z.ZodOptional<z.ZodString>;
         meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        intentId: z.ZodString;
+        claimId: z.ZodString;
         action: z.ZodString;
         declaredAt: z.ZodNumber;
         expiresAt: z.ZodNumber;
@@ -320,8 +520,19 @@ export declare const presenceUpdateFrameSchema: z.ZodObject<{
             code: z.ZodString;
             message: z.ZodOptional<z.ZodString>;
             heldBy: z.ZodOptional<z.ZodString>;
-            heldByIntentId: z.ZodOptional<z.ZodString>;
+            heldByClaimId: z.ZodOptional<z.ZodString>;
             heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+            heldByClaim: z.ZodOptional<z.ZodObject<{
+                field: z.ZodOptional<z.ZodString>;
+                entityType: z.ZodString;
+                entityId: z.ZodString;
+                meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                claimId: z.ZodString;
+                action: z.ZodString;
+                declaredAt: z.ZodNumber;
+                expiresAt: z.ZodNumber;
+            }, z.core.$strip>>;
+            policyReason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
     delegatedFrom: z.ZodOptional<z.ZodNullable<z.ZodString>>;