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

package/README.md

@@ -69,7 +69,7 @@ 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
+`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
@@ -302,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

@@ -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[]}
@@ -225,6 +303,20 @@ class ClaimRegistry {
         }
         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[]}
@@ -252,6 +344,19 @@ class ClaimRegistry {
         }
         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
@@ -264,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
@@ -1951,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;
@@ -2042,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;
@@ -2110,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

@@ -143,6 +143,24 @@ 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 (a stored processed/failed intent, optionally parked), and
@@ -181,6 +199,14 @@ export class ClaimRegistry {
   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.9.0",
+  "version": "2.10.0",
   "description": "Shared Band event-payload validation",
   "license": "MIT",
   "repository": {