@band-ai/band-sdk-core 2.5.0 → 2.6.0

package/README.md

@@ -107,6 +107,31 @@ switch (tracker.recordRoomParticipantsJoinFailed("room-1", ticket, false)) {
 }
 ```
 
+### `DecisionRegistry` lifecycle
+
+`DecisionRegistry` tracks chat-mediated asks: whoever claims one first owns
+its outcome. Every registration returns `[token, ticket]`, with `ticket` a
+`bigint`, and later calls name that exact registration, so a stale holder
+gets `"stale"` instead of acting on a newer ask that reused the token.
+`maxPending` must be an integer of at least `1`, or omitted/`null` for
+unbounded; `seed` is an optional `bigint`. `cancelAll`/`cancelRoom` return a
+plain `{ unclaimed, claimed }` object. `isAuthorizedSender` takes an array,
+a `Set`, or `null`.
+
+```ts
+import { DecisionRegistry, isAuthorizedSender } from "@band-ai/band-sdk-core";
+
+const registry = new DecisionRegistry(10);
+const registration = registry.registerMinted("room-1");
+if (registration === undefined) throw new Error("tickets exhausted");
+const [token, ticket] = registration;
+
+if (registry.tryClaim(token, ticket) !== "claimed") throw new Error("not claimed");
+if (registry.tryClaim(token, ticket) !== "already_claimed") throw new Error("claimed twice");
+if (registry.cancelRoom("room-1").claimed[0] !== token) throw new Error("claim not reported");
+if (!isAuthorizedSender(new Set(["alice"]), "alice")) throw new Error("alice refused");
+```
+
 ### `Session` — WebSocket reconnect state machine
 
 `Session`/`SessionPolicy` are a sans-io session state machine plus

package/band_sdk_core.js

@@ -270,6 +270,182 @@ class ClaimRegistry {
 if (Symbol.dispose) ClaimRegistry.prototype[Symbol.dispose] = ClaimRegistry.prototype.free;
 exports.ClaimRegistry = ClaimRegistry;
 
+/**
+ * Pending chat-mediated asks by token, oldest first. Every registration
+ * returns `[token, ticket]`; later calls name that exact registration, so a
+ * stale holder never acts on a newer ask that reused the token.
+ */
+class DecisionRegistry {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        DecisionRegistryFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_decisionregistry_free(ptr, 0);
+    }
+    /**
+     * Returns a plain `{ unclaimed, claimed }` object of token arrays.
+     * @returns {any}
+     */
+    cancelAll() {
+        const ret = wasm.decisionregistry_cancelAll(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * Returns a plain `{ unclaimed, claimed }` object of token arrays.
+     * @param {any} roomId
+     * @returns {any}
+     */
+    cancelRoom(roomId) {
+        const ret = wasm.decisionregistry_cancelRoom(this.__wbg_ptr, roomId);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @returns {string | undefined}
+     */
+    evictOldest() {
+        const ret = wasm.decisionregistry_evictOldest(this.__wbg_ptr);
+        let v1;
+        if (ret[0] !== 0) {
+            v1 = getStringFromWasm0(ret[0], ret[1]);
+            wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        }
+        return v1;
+    }
+    /**
+     * @param {any} token
+     * @param {bigint} ticket
+     * @returns {boolean}
+     */
+    forget(token, ticket) {
+        const ret = wasm.decisionregistry_forget(this.__wbg_ptr, token, ticket);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @returns {number | undefined}
+     */
+    get maxPending() {
+        const ret = wasm.decisionregistry_maxPending(this.__wbg_ptr);
+        return ret === Number.MAX_SAFE_INTEGER ? undefined : ret;
+    }
+    /**
+     * `maxPending` omitted or `null` never evicts. `seed` fixes the
+     * minted-token sequence; omitted, each registry draws its own.
+     * @param {number | null} [maxPending]
+     * @param {bigint | null} [seed]
+     */
+    constructor(maxPending, seed) {
+        const ret = wasm.decisionregistry_new(!isLikeNone(maxPending), isLikeNone(maxPending) ? 0 : maxPending, !isLikeNone(seed), isLikeNone(seed) ? BigInt(0) : seed);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0];
+        DecisionRegistryFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * @returns {string | undefined}
+     */
+    oldestUnclaimed() {
+        const ret = wasm.decisionregistry_oldestUnclaimed(this.__wbg_ptr);
+        let v1;
+        if (ret[0] !== 0) {
+            v1 = getStringFromWasm0(ret[0], ret[1]);
+            wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        }
+        return v1;
+    }
+    /**
+     * @param {any} key
+     * @returns {Array<any> | undefined}
+     */
+    registerKeyed(key) {
+        const ret = wasm.decisionregistry_registerKeyed(this.__wbg_ptr, key);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @param {any} roomId
+     * @returns {Array<any> | undefined}
+     */
+    registerMinted(roomId) {
+        const ret = wasm.decisionregistry_registerMinted(this.__wbg_ptr, roomId);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @param {any} token
+     * @param {bigint} ticket
+     * @returns {string}
+     */
+    tryClaim(token, ticket) {
+        const ret = wasm.decisionregistry_tryClaim(this.__wbg_ptr, token, ticket);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return getStringFromWasm0(ret[0], ret[1]);
+    }
+    /**
+     * @returns {number}
+     */
+    unclaimedCount() {
+        const ret = wasm.decisionregistry_unclaimedCount(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * @param {any} roomId
+     * @returns {string[]}
+     */
+    unclaimedInRoom(roomId) {
+        const ret = wasm.decisionregistry_unclaimedInRoom(this.__wbg_ptr, roomId);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * @returns {string[]}
+     */
+    unclaimed() {
+        const ret = wasm.decisionregistry_unclaimed(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * @param {any} token
+     * @param {bigint} ticket
+     * @returns {boolean}
+     */
+    withdraw(token, ticket) {
+        const ret = wasm.decisionregistry_withdraw(this.__wbg_ptr, token, ticket);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+}
+if (Symbol.dispose) DecisionRegistry.prototype[Symbol.dispose] = DecisionRegistry.prototype.free;
+exports.DecisionRegistry = DecisionRegistry;
+
 /**
  * The always-injected passive participant roster. A participant is any
  * plain object; `add`/`setAll` read `id`, `name`, `type`, `handle`,
@@ -1387,6 +1563,24 @@ function evaluateNextMessage(triggeringMessageId, nextMessageId) {
 }
 exports.evaluateNextMessage = evaluateNextMessage;
 
+/**
+ * Whether `senderId` may answer an ask: `null` admits anyone; any array or
+ * `Set` -- empty included -- admits only its members. Throws a plain
+ * `Error` if `authorizedSenders` is not an array or `Set` of strings (or
+ * `null`), or `senderId` is not a string (or `null`).
+ * @param {any} authorizedSenders
+ * @param {any} senderId
+ * @returns {boolean}
+ */
+function isAuthorizedSender(authorizedSenders, senderId) {
+    const ret = wasm.isAuthorizedSender(authorizedSenders, senderId);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0] !== 0;
+}
+exports.isAuthorizedSender = isAuthorizedSender;
+
 /**
  * The one definition of "self echo" (`senderType === "Agent" &&
  * senderId === agentId`), shared by `evaluateDeliveryEvent` and
@@ -1643,6 +1837,10 @@ function __wbg_get_imports() {
             const ret = Object.entries(arg0);
             return ret;
         },
+        __wbg_from_a39669ce566077da: function(arg0) {
+            const ret = Array.from(arg0);
+            return ret;
+        },
         __wbg_get_6cf5a4d4d8ad3c5a: function() { return handleError(function (arg0, arg1) {
             const ret = Reflect.get(arg0, arg1);
             return ret;
@@ -1683,6 +1881,16 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
+        __wbg_instanceof_Set_daa5e1ad3c6acaeb: function(arg0) {
+            let result;
+            try {
+                result = arg0 instanceof Set;
+            } catch (_) {
+                result = false;
+            }
+            const ret = result;
+            return ret;
+        },
         __wbg_instanceof_Uint8Array_598adc0fef426aa8: function(arg0) {
             let result;
             try {
@@ -1752,6 +1960,10 @@ function __wbg_get_imports() {
             const ret = arg0.push(arg1);
             return ret;
         },
+        __wbg_random_7bce4e9e78e2e0d0: function() {
+            const ret = Math.random();
+            return ret;
+        },
         __wbg_set_13d25b81ab403f5e: function(arg0, arg1, arg2) {
             arg0[arg1 >>> 0] = arg2;
         },
@@ -1812,6 +2024,9 @@ const AgentFailureFinalization = (typeof FinalizationRegistry === 'undefined')
 const ClaimRegistryFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_claimregistry_free(ptr, 1));
+const DecisionRegistryFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_decisionregistry_free(ptr, 1));
 const ParticipantRosterFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_participantroster_free(ptr, 1));

package/index.d.ts

@@ -419,6 +419,56 @@ export class RoomRoster {
   clear(): string[];
 }
 
+export type ClaimOutcome = "claimed" | "already_claimed" | "stale";
+
+/** What a cancellation removed, oldest first. */
+export interface CancelledDecisions {
+  /** Asks nobody claimed -- the caller resolves these. */
+  unclaimed: string[];
+  /** Asks whose claimant still resolves them. */
+  claimed: string[];
+}
+
+/**
+ * Pending chat-mediated asks by token, oldest first. Every registration
+ * returns `[token, ticket]`; later calls name that exact registration, so a
+ * stale holder never acts on a newer ask that reused the token.
+ *
+ * Throws if `maxPending` is not an integer in `1..=4294967295` -- a zero
+ * capacity would evict every ask the moment it arrives -- or if `seed` is
+ * not a `bigint`. Omitted or `null`, `maxPending` never evicts; omitted,
+ * `seed` is drawn fresh. Every `token`/`key`/`roomId` argument below throws
+ * a plain `Error` if it is not a string, and every `ticket` if it is not a
+ * `bigint`.
+ */
+export class DecisionRegistry {
+  constructor(maxPending?: number | null, seed?: bigint);
+  readonly maxPending: number | undefined;
+  registerMinted(roomId?: string | null): [token: string, ticket: bigint] | undefined;
+  registerKeyed(key: string): [token: string, ticket: bigint] | undefined;
+  tryClaim(token: string, ticket: bigint): ClaimOutcome;
+  withdraw(token: string, ticket: bigint): boolean;
+  forget(token: string, ticket: bigint): boolean;
+  unclaimed(): string[];
+  unclaimedInRoom(roomId: string): string[];
+  unclaimedCount(): number;
+  oldestUnclaimed(): string | undefined;
+  evictOldest(): string | undefined;
+  cancelAll(): CancelledDecisions;
+  cancelRoom(roomId: string): CancelledDecisions;
+}
+
+/**
+ * Whether `senderId` may answer an ask: `null` admits anyone; any array or
+ * `Set` -- empty included -- admits only its members. Throws a plain `Error`
+ * if `authorizedSenders` is not an array or `Set` of strings (a bare string
+ * included) or `null`, or if `senderId` is not a string or `null`.
+ */
+export function isAuthorizedSender(
+  authorizedSenders: readonly string[] | ReadonlySet<string> | null,
+  senderId: string | null,
+): boolean;
+
 // The one-shot delivery lifecycle decisions: evaluateDeliveryEvent,
 // evaluateNextMessage, evaluateDrainCandidate, evaluateAdapterResult.
 // Each returns a plain tagged object -- these functions carry no

package/package.json

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