@band-ai/band-sdk-core 2.8.0 → 2.9.0

package/README.md

@@ -68,6 +68,15 @@ snapshot names the same `id` twice. `RetryTracker`'s `maxTracked` must be
 at least `1`; `0` throws. `ClaimRegistry`'s `maxCompleted` must be at
 least `1` too — `0` also throws.
 
+`ClaimRegistry` keeps one terminal intent per message until
+`rememberCompleted`: `rememberAckPending` records a processed write and
+`rememberFailedAckPending` a failed one carrying its `error`. The first
+intent wins; a different one throws — leaving the entry unchanged, with
+`.issues` and `.traceContext` attached — and an identical repeat is a
+no-op. `pendingAck` returns `{status, error?, parked}` or `undefined`.
+`parkAck` takes a `ParkedReason` wire name, `parkedReasons()` lists them,
+and any other value throws a plain `Error`.
+
 `SubscriptionTracker` provides synchronous, transport-independent decisions for
 agent-topic joins and the two-topic room subscription transaction. Its opaque
 tickets are JavaScript `bigint` values and must be supplied when recording a

package/band_sdk_core.js

@@ -118,8 +118,8 @@ exports.AgentFailure = AgentFailure;
 
 /**
  * Ownership ledger for the inbound message-delivery lifecycle: in-flight,
- * ack-pending, and completed states, each scoped by `(roomId,
- * messageId)`.
+ * ack-pending (a stored processed/failed intent, optionally parked), and
+ * completed states, each scoped by `(roomId, messageId)`.
  */
 class ClaimRegistry {
     __destroy_into_raw() {
@@ -210,6 +210,21 @@ class ClaimRegistry {
         ClaimRegistryFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
+    /**
+     * Mark a pending entry parked for `reason` (`"not_found"` or
+     * `"rejected"`); `false` when nothing is pending for the message.
+     * @param {any} room_id
+     * @param {any} message_id
+     * @param {any} reason
+     * @returns {boolean}
+     */
+    parkAck(room_id, message_id, reason) {
+        const ret = wasm.claimregistry_parkAck(this.__wbg_ptr, room_id, message_id, reason);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
     /**
      * @param {any} room_id
      * @returns {string[]}
@@ -223,6 +238,20 @@ class ClaimRegistry {
         wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
         return v1;
     }
+    /**
+     * The pending entry as `{status: "processed" | "failed", error?:
+     * string, parked: "not_found" | "rejected" | null}`, or `undefined`.
+     * @param {any} room_id
+     * @param {any} message_id
+     * @returns {any}
+     */
+    pendingAck(room_id, message_id) {
+        const ret = wasm.claimregistry_pendingAck(this.__wbg_ptr, room_id, message_id);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {any} room_id
      * @param {any} message_id
@@ -265,6 +294,21 @@ class ClaimRegistry {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * Record a failed turn awaiting a durable failed write carrying
+     * `error`. Throws if a different intent is already pending, with
+     * `.issues` and `.traceContext`.
+     * @param {any} room_id
+     * @param {any} message_id
+     * @param {any} error
+     * @param {any} traceContext
+     */
+    rememberFailedAckPending(room_id, message_id, error, traceContext) {
+        const ret = wasm.claimregistry_rememberFailedAckPending(this.__wbg_ptr, room_id, message_id, error, traceContext);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * @param {any} room_id
      * @param {any} message_id
@@ -277,6 +321,17 @@ class ClaimRegistry {
         }
         return ret[0] !== 0;
     }
+    /**
+     * @param {any} room_id
+     * @returns {number}
+     */
+    unparkAcks(room_id) {
+        const ret = wasm.claimregistry_unparkAcks(this.__wbg_ptr, room_id);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] >>> 0;
+    }
 }
 if (Symbol.dispose) ClaimRegistry.prototype[Symbol.dispose] = ClaimRegistry.prototype.free;
 exports.ClaimRegistry = ClaimRegistry;
@@ -1791,6 +1846,18 @@ function noReplyTool() {
 }
 exports.noReplyTool = noReplyTool;
 
+/**
+ * r" Every `ClaimRegistry.parkAck` reason, in declaration order.
+ * @returns {string[]}
+ */
+function parkedReasons() {
+    const ret = wasm.parkedReasons();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.parkedReasons = parkedReasons;
+
 /**
  * This platform's Phoenix Channels topic for a room's `room_participants`
  * channel.

package/index.d.ts

@@ -128,9 +128,25 @@ export interface ParticipantFields {
   description?: string | null;
 }
 
+/**
+ * Why the platform refused a terminal write that stays pending:
+ * `not_found` when the message or room is not visible, `rejected` when it
+ * proved no processing attempt exists to settle.
+ */
+export type ParkedReason = "not_found" | "rejected";
+
+/** Every {@link ParkedReason} wire name, in declaration order. */
+export function parkedReasons(): ParkedReason[];
+
+/** A pending entry: its fixed terminal intent plus whether it is parked. */
+export type PendingAck =
+  | { status: "processed"; parked: ParkedReason | null }
+  | { status: "failed"; error: string; parked: ParkedReason | null };
+
 /**
  * Ownership ledger for the inbound message-delivery lifecycle: in-flight,
- * ack-pending, and completed states, each scoped by `(roomId, messageId)`.
+ * ack-pending (a stored processed/failed intent, optionally parked), and
+ * completed states, each scoped by `(roomId, messageId)`.
  *
  * Throws if `maxCompleted` is not a non-negative integer in range, or is
  * `0` -- a zero capacity would evict every completed entry the instant it
@@ -149,6 +165,20 @@ export class ClaimRegistry {
   rememberCompleted(roomId: string, messageId: string): void;
   isAckPending(roomId: string, messageId: string): boolean;
   rememberAckPending(roomId: string, messageId: string): void;
+  /**
+   * Throws if a different terminal intent is already pending, with `.issues`
+   * and `.traceContext`.
+   */
+  rememberFailedAckPending(
+    roomId: string,
+    messageId: string,
+    error: string,
+    traceContext?: string | null,
+  ): void;
+  pendingAck(roomId: string, messageId: string): PendingAck | undefined;
+  /** `false` when nothing is pending for the message; throws on an unknown reason. */
+  parkAck(roomId: string, messageId: string, reason: ParkedReason): boolean;
+  unparkAcks(roomId: string): number;
   pendingAckIds(roomId: string): string[];
   recordAckRetry(roomId: string, messageId: string): number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@band-ai/band-sdk-core",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Shared Band event-payload validation",
   "license": "MIT",
   "repository": {