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

package/LICENSE

@@ -0,0 +1,54 @@
+Band SDK License Agreement
+
+Copyright (c) 2025-2026 THENVOI AI LTD. D/B/A BAND. All rights reserved.
+
+By using or redistributing the SDK, you agree to this agreement. If you
+do not agree, do not use or redistribute it.
+
+1. License grant
+Band grants you a non-exclusive, worldwide, royalty-free license to use
+the SDK's compiled binaries to develop and run applications that integrate
+with Band, including commercial applications. You may reproduce and
+redistribute unmodified SDK binaries as dependencies of those applications,
+provided you include this agreement and preserve all copyright, attribution,
+and third-party notices. Recipients receive their SDK rights under this
+agreement. Access to Band services remains subject to their separate terms.
+
+2. Binary-only distribution
+The license covers compiled Python extensions and WebAssembly binaries,
+and the accompanying public interface declarations, generated JavaScript
+loaders, Python package loaders, and documentation supplied by Band. Those
+auxiliary files may be distributed with the binaries under section 1.
+No license to the SDK's Rust implementation source or private repository
+is granted. Repository access does not authorize source redistribution.
+
+3. Restrictions
+Except as expressly permitted above or required by applicable law, you may
+not modify the SDK, distribute it as a standalone competing SDK, disclose
+or distribute its implementation source, or reverse engineer, decompile,
+or disassemble the binaries. No trademark rights are granted. Band retains
+all ownership and all rights not expressly granted by this agreement.
+
+4. Third-party components
+Third-party components remain governed by their own licenses. This
+agreement does not limit rights granted by those licenses. Preserve their
+required notices when redistributing the SDK.
+
+5. No warranty; limitation of liability
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SDK IS PROVIDED "AS IS" WITHOUT
+WARRANTIES OF ANY KIND, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, AND NON-INFRINGEMENT. BAND SHALL NOT BE LIABLE FOR INDIRECT,
+INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR LOSS OF DATA,
+PROFITS, OR BUSINESS ARISING FROM USE OF THE SDK. NOTHING IN THIS AGREEMENT
+EXCLUDES LIABILITY THAT CANNOT LAWFULLY BE EXCLUDED.
+
+6. Termination
+Your license terminates if you breach this agreement. On termination, stop
+using and distributing the SDK and delete your copies, except copies you
+must retain by law. Compliant recipients of previously redistributed SDK
+binaries retain their licenses. Sections 2 through 6 survive termination.
+
+7. Scope
+This agreement applies to SDK copies supplied with it. It does not replace
+licenses previously granted for earlier releases. A separately signed
+agreement with Band takes precedence to the extent of a conflict.

package/README.md

@@ -5,7 +5,7 @@ runtime state, compiled from Rust to WebAssembly for Node. Every function
 is synchronous, pure computation — no network, filesystem, or logging.
 
 ```
-band-sdk-core-core (Rust)  -->  @band-ai/band-sdk-core (this package, npm)  -->  band-sdk-typescript
+band-sdk-core (Rust)  -->  @band-ai/band-sdk-core (this package, npm)  -->  band-sdk-typescript
 ```
 
 If you're using [`band-sdk-typescript`](https://github.com/band-ai/band-sdk-typescript),
@@ -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
@@ -301,4 +301,32 @@ just build-wasm  # Node package output
 
 ## License
 
-MIT — see [LICENSE](https://github.com/band-ai/band-sdk-core/blob/main/LICENSE).
+Proprietary, binary-only Band SDK License Agreement — see the bundled
+[LICENSE](LICENSE). The Rust implementation source is private.
+
+## 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;
@@ -2114,6 +2261,10 @@ function __wbg_get_imports() {
             const ret = Array.isArray(arg0);
             return ret;
         },
+        __wbg_isArray_fcec83e4012ff365: function() { return handleError(function (arg0) {
+            const ret = Array.isArray(arg0);
+            return ret;
+        }, arguments); },
         __wbg_isSafeInteger_717808ad6a54bd9e: function(arg0) {
             const ret = Number.isSafeInteger(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,8 +1,8 @@
 {
   "name": "@band-ai/band-sdk-core",
-  "version": "2.9.0",
+  "version": "3.0.0",
   "description": "Shared Band event-payload validation",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
     "url": "https://github.com/band-ai/band-sdk-core"
@@ -11,7 +11,8 @@
     "band_sdk_core.js",
     "band_sdk_core_bg.wasm",
     "index.d.ts",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "main": "./band_sdk_core.js",
   "types": "./index.d.ts",