@band-ai/band-sdk-core 2.8.0 → 2.10.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` or matching `confirmSettlement`: `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
@@ -293,3 +302,30 @@ just build-wasm  # Node package output
 ## License
 
 MIT — see [LICENSE](https://github.com/band-ai/band-sdk-core/blob/main/LICENSE).
+
+## Fenced delivery settlement
+
+`guardedClaim` shares eligibility across discovery paths. Its optional facts
+object accepts boolean `self_echo`, `durably_processed`, `durably_failed`, and
+`allow_failed_retry` fields. Only `allow_failed_retry` defaults to true. Unknown
+fields and non-boolean values throw before ownership changes.
+
+Pending originals remain excluded when parked. Record the terminal disposition
+before transport and confirm only after acceptance and a current-execution check.
+Retry confirmation restores charged attempts with the stricter retry ceiling;
+it does not falsely complete the original. Tokens are opaque local strings.
+
+```ts
+import { ClaimRegistry, RetryTracker } from "@band-ai/band-sdk-core";
+
+const claims = new ClaimRegistry();
+const previous = new RetryTracker(3);
+if (claims.guardedClaim("room", "message", previous) !== "runnable") throw new Error("not admitted");
+previous.recordAttempt("message");
+const pending = claims.recordFailedSettlement("room", "message", "failure", previous, true);
+claims.release("room", "message");
+const current = new RetryTracker(3);
+if (!claims.confirmSettlement("room", "message", pending.token, current)) throw new Error("not confirmed");
+if (claims.isCompleted("room", "message")) throw new Error("retry falsely completed");
+if (current.recordAttempt("message")[0] !== 2) throw new Error("charge lost");
+```

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() {
@@ -145,6 +145,47 @@ class ClaimRegistry {
         wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
         return v1;
     }
+    /**
+     * @param {any} room_id
+     * @param {any} message_id
+     * @param {any} token
+     * @param {RetryTracker} retry_tracker
+     * @returns {boolean}
+     */
+    confirmSettlement(room_id, message_id, token, retry_tracker) {
+        _assertClass(retry_tracker, RetryTracker);
+        const ret = wasm.claimregistry_confirmSettlement(this.__wbg_ptr, room_id, message_id, token, retry_tracker.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} room_id
+     * @param {any} message_id
+     * @param {RetryTracker} retry_tracker
+     * @param {any} facts
+     * @returns {string}
+     */
+    deliveryEligibility(room_id, message_id, retry_tracker, facts) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            _assertClass(retry_tracker, RetryTracker);
+            const ret = wasm.claimregistry_deliveryEligibility(this.__wbg_ptr, room_id, message_id, retry_tracker.__wbg_ptr, facts);
+            var ptr1 = ret[0];
+            var len1 = ret[1];
+            if (ret[3]) {
+                ptr1 = 0; len1 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
     /**
      * @param {any} room_id
      */
@@ -154,6 +195,43 @@ class ClaimRegistry {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * @param {any} room_id
+     * @param {any} message_id
+     * @param {RetryTracker} retry_tracker
+     * @param {any} facts
+     * @returns {string}
+     */
+    guardedClaim(room_id, message_id, retry_tracker, facts) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            _assertClass(retry_tracker, RetryTracker);
+            const ret = wasm.claimregistry_guardedClaim(this.__wbg_ptr, room_id, message_id, retry_tracker.__wbg_ptr, facts);
+            var ptr1 = ret[0];
+            var len1 = ret[1];
+            if (ret[3]) {
+                ptr1 = 0; len1 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * @param {any} room_id
+     * @returns {boolean}
+     */
+    hasRetryableSettlement(room_id) {
+        const ret = wasm.claimregistry_hasRetryableSettlement(this.__wbg_ptr, room_id);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
     /**
      * @param {any} room_id
      * @returns {string[]}
@@ -210,6 +288,35 @@ 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
+     * @param {any} message_id
+     * @param {any} token
+     * @param {any} reason
+     * @returns {boolean}
+     */
+    parkSettlement(room_id, message_id, token, reason) {
+        const ret = wasm.claimregistry_parkSettlement(this.__wbg_ptr, room_id, message_id, token, reason);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
     /**
      * @param {any} room_id
      * @returns {string[]}
@@ -223,6 +330,33 @@ 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
+     * @param {any} trace_context
+     * @returns {any}
+     */
+    pendingSettlement(room_id, message_id, trace_context) {
+        const ret = wasm.claimregistry_pendingSettlement(this.__wbg_ptr, room_id, message_id, trace_context);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {any} room_id
      * @param {any} message_id
@@ -235,6 +369,36 @@ class ClaimRegistry {
         }
         return ret[0] >>> 0;
     }
+    /**
+     * @param {any} room_id
+     * @param {any} message_id
+     * @param {any} error
+     * @param {RetryTracker} retry_tracker
+     * @param {any} allow_retry
+     * @param {any} trace_context
+     * @returns {any}
+     */
+    recordFailedSettlement(room_id, message_id, error, retry_tracker, allow_retry, trace_context) {
+        _assertClass(retry_tracker, RetryTracker);
+        const ret = wasm.claimregistry_recordFailedSettlement(this.__wbg_ptr, room_id, message_id, error, retry_tracker.__wbg_ptr, allow_retry, trace_context);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @param {any} room_id
+     * @param {any} message_id
+     * @param {any} trace_context
+     * @returns {any}
+     */
+    recordProcessedSettlement(room_id, message_id, trace_context) {
+        const ret = wasm.claimregistry_recordProcessedSettlement(this.__wbg_ptr, room_id, message_id, trace_context);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {any} room_id
      * @param {any} message_id
@@ -265,6 +429,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 +456,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 +1981,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.
@@ -1884,6 +2086,14 @@ exports.validateMemoryTypeForSystem = validateMemoryTypeForSystem;
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
+        __wbg_0_c2e12945caff5360: function(arg0) {
+            const ret = arg0["0"];
+            return ret;
+        },
+        __wbg_1_191c69f1437bcd10: function(arg0) {
+            const ret = arg0["1"];
+            return ret;
+        },
         __wbg_Error_30c8987f7c2ed4e2: function(arg0, arg1) {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return ret;
@@ -1975,6 +2185,10 @@ function __wbg_get_imports() {
             const ret = arg0.done;
             return ret;
         },
+        __wbg_entries_b6763c9f1557e886: function() { return handleError(function (arg0) {
+            const ret = Object.entries(arg0);
+            return ret;
+        }, arguments); },
         __wbg_entries_fb6397112b1de25f: function(arg0) {
             const ret = Object.entries(arg0);
             return ret;
@@ -2043,6 +2257,10 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
+        __wbg_isArray_cff2824818301a8c: function() { return handleError(function (arg0) {
+            const ret = Array.isArray(arg0);
+            return ret;
+        }, arguments); },
         __wbg_isArray_e15a2ff68ffdbef2: function(arg0) {
             const ret = Array.isArray(arg0);
             return ret;

package/index.d.ts

@@ -128,9 +128,43 @@ 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 };
+
+export type DeliveryEligibility = "self" | "completed" | "pending" | "inflight" | "exhausted" | "failed" | "runnable";
+
+export interface DeliveryFacts {
+  self_echo?: boolean;
+  durably_processed?: boolean;
+  durably_failed?: boolean;
+  allow_failed_retry?: boolean;
+}
+
+export type SettlementContinuation =
+  | { kind: "finished" }
+  | { kind: "retry"; attempts: number; max_retries: number };
+
+export type PendingSettlement = PendingAck & {
+  token: string;
+  continuation: SettlementContinuation;
+};
+
 /**
  * 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,8 +183,30 @@ 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;
+  deliveryEligibility(roomId: string, messageId: string, retryTracker: RetryTracker, facts?: DeliveryFacts): DeliveryEligibility;
+  guardedClaim(roomId: string, messageId: string, retryTracker: RetryTracker, facts?: DeliveryFacts): DeliveryEligibility;
+  hasRetryableSettlement(roomId: string): boolean;
+  pendingSettlement(roomId: string, messageId: string, traceContext?: string | null): PendingSettlement | undefined;
+  recordProcessedSettlement(roomId: string, messageId: string, traceContext?: string | null): PendingSettlement;
+  recordFailedSettlement(roomId: string, messageId: string, error: string, retryTracker: RetryTracker, allowRetry: boolean, traceContext?: string | null): PendingSettlement;
+  confirmSettlement(roomId: string, messageId: string, token: string, retryTracker: RetryTracker): boolean;
+  parkSettlement(roomId: string, messageId: string, token: string, reason: ParkedReason): boolean;
 }
 
 /**

package/package.json

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