@band-ai/band-sdk-core 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,138 @@
+# @band-ai/band-sdk-core
+
+Shared Band event-payload validation, memory-taxonomy, and inbound-delivery
+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
+```
+
+If you're using [`band-sdk-typescript`](https://github.com/band-ai/band-sdk-typescript),
+it already depends on this package — you don't need to install it
+yourself. Install it directly only if you're calling into it without that
+SDK. Full picture: [repository architecture](https://github.com/band-ai/band-sdk-core#architecture).
+
+## Install
+
+```bash
+npm install @band-ai/band-sdk-core
+```
+
+The package is Node CommonJS with an eager WASM load — there is no `init`
+step, and no Rust or `wasm-pack` toolchain needed to install. Both
+`require()` and ESM `import()` resolve it at the package root.
+
+## Quickstart
+
+```js
+const { validateEventPayload } = require("@band-ai/band-sdk-core");
+
+try {
+  const payload = validateEventPayload("room_deleted", { id: "room-1" });
+} catch (err) {
+  for (const { path, code, message } of err.issues) {
+    console.error(`${path}: ${code} - ${message}`);
+  }
+}
+```
+
+`validateEventPayload` is the platform's inbound WebSocket payload policy:
+normalize a well-formed payload, or throw with every violation reported at
+once, never just the first.
+
+## Public surface
+
+### `validateEventPayload(eventType, raw, traceContext?)`
+
+`eventType` is the platform event name (`"message_created"`,
+`"agent.control"`, …). `raw` is a plain JS value. Success returns the
+normalized payload (`event_created` returns the input unchanged). Failure
+throws a native `Error` with `.issues` (`{path, code, message}` objects)
+and `.traceContext` — not a message-only error. There is no custom
+exception class.
+
+### Delivery-state runtime classes
+
+`ClaimRegistry`, `RetryTracker`, `ParticipantRoster`, and `SubscriptionTracker` are the
+inbound-delivery runtime state classes — lifecycle and design decisions:
+[`runtime-state-policy.md`](https://github.com/band-ai/band-sdk-core/blob/main/crates/core/docs/runtime-state-policy.md).
+
+A participant is any plain object; `add`/`setAll` read `id`, `name`,
+`type`, `handle`, `description` from it and `list()` returns objects with
+exactly those five keys. `id` is required and must be a string; the other
+four are each a string or `null`/absent. `setAll` takes an optional
+`traceContext` and throws — leaving the roster unchanged, with `.issues`
+and `.traceContext` attached like `validateEventPayload`'s error — if its
+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.
+
+`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
+completion. Failed rollbacks and failed or unknown leaves require explicit
+reconciliation before a fresh claim is allowed.
+
+### `SubscriptionTracker` lifecycle
+
+```ts
+import { SubscriptionTracker } from "@band-ai/band-sdk-core";
+
+const tracker = new SubscriptionTracker();
+const ticket = tracker.beginRoomSubscribe("room-1");
+if (ticket === undefined) throw new Error("room is not claimable");
+
+switch (tracker.recordRoomParticipantsJoinFailed("room-1", ticket, false)) {
+  case "rollback_failed":
+    if (tracker.roomStatus("room-1") !== "needs_reconciliation") {
+      throw new Error("rollback state was not retained");
+    }
+    tracker.acknowledgeRoomReconciled("room-1");
+    const retryTicket = tracker.beginRoomSubscribe("room-1");
+    if (retryTicket === undefined) throw new Error("reconciled room is not claimable");
+    if (tracker.recordBothRoomTopicsJoined("room-1", retryTicket) !== "subscribed") {
+      throw new Error("room did not subscribe");
+    }
+    const leaveTicket = tracker.unsubscribeRoom("room-1");
+    if (leaveTicket === undefined || !tracker.markRoomLeaveComplete("room-1", leaveTicket, "left")) {
+      throw new Error("room did not leave");
+    }
+    break;
+  case "subscribed":
+  case "join_failed":
+  case "rolled_back":
+  case "stale":
+    break;
+}
+```
+
+### `validateMemoryTypeForSystem(system, type, traceContext?)`
+
+Validates the canonical memory taxonomy — design decisions:
+[`memory-taxonomy-policy.md`](https://github.com/band-ai/band-sdk-core/blob/main/crates/core/docs/memory-taxonomy-policy.md).
+`system` and `type` are wire-name strings (`MemorySystem`/`MemoryType` in
+`index.d.ts` are string-literal types, not classes — there is no runtime
+enum on this boundary, matching how `EventType` stays a plain string in
+`validateEventPayload`). Returns `void` on success. Failure throws a
+native `Error` with the same `.issues`/`.traceContext` contract as
+`validateEventPayload` — an unrecognized `system` and an unrecognized
+`type` are independent issues, both reported when both strings are
+invalid.
+
+The public declaration is
+[`index.d.ts`](https://github.com/band-ai/band-sdk-core/blob/main/crates/wasm/index.d.ts).
+
+## Build / test
+
+`just check` compiles and lints this crate for the host.
+
+```bash
+just test-wasm   # suite in Node
+just pack-npm    # Node tarball + require/import consumers
+just build-wasm  # Node package output
+```
+
+## License
+
+MIT — see [LICENSE](https://github.com/band-ai/band-sdk-core/blob/main/LICENSE).

package/band_sdk_core.js

@@ -348,6 +348,264 @@ class RetryTracker {
 if (Symbol.dispose) RetryTracker.prototype[Symbol.dispose] = RetryTracker.prototype.free;
 exports.RetryTracker = RetryTracker;
 
+/**
+ * Transport-independent subscription decisions for one agent session.
+ */
+class SubscriptionTracker {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        SubscriptionTrackerFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_subscriptiontracker_free(ptr, 0);
+    }
+    /**
+     * @param {any} topic
+     * @returns {boolean}
+     */
+    acknowledgeAgentTopicReconciled(topic) {
+        const ret = wasm.subscriptiontracker_acknowledgeAgentTopicReconciled(this.__wbg_ptr, topic);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} room_id
+     * @returns {boolean}
+     */
+    acknowledgeRoomReconciled(room_id) {
+        const ret = wasm.subscriptiontracker_acknowledgeRoomReconciled(this.__wbg_ptr, room_id);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} topic
+     * @returns {string}
+     */
+    agentTopicStatus(topic) {
+        const ret = wasm.subscriptiontracker_agentTopicStatus(this.__wbg_ptr, topic);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return getStringFromWasm0(ret[0], ret[1]);
+    }
+    /**
+     * @param {any} topic
+     * @returns {bigint | undefined}
+     */
+    beginAgentTopicJoin(topic) {
+        const ret = wasm.subscriptiontracker_beginAgentTopicJoin(this.__wbg_ptr, topic);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return ret[0] === 0 ? undefined : BigInt.asUintN(64, ret[1]);
+    }
+    /**
+     * @param {any} room_id
+     * @returns {bigint | undefined}
+     */
+    beginRoomSubscribe(room_id) {
+        const ret = wasm.subscriptiontracker_beginRoomSubscribe(this.__wbg_ptr, room_id);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return ret[0] === 0 ? undefined : BigInt.asUintN(64, ret[1]);
+    }
+    endSession() {
+        wasm.subscriptiontracker_endSession(this.__wbg_ptr);
+    }
+    /**
+     * @param {any} topic
+     * @param {bigint} ticket
+     * @returns {boolean}
+     */
+    isAgentTopicClaimCurrent(topic, ticket) {
+        const ret = wasm.subscriptiontracker_isAgentTopicClaimCurrent(this.__wbg_ptr, topic, ticket);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} topic
+     * @returns {boolean}
+     */
+    isAgentTopicJoined(topic) {
+        const ret = wasm.subscriptiontracker_isAgentTopicJoined(this.__wbg_ptr, topic);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} room_id
+     * @param {bigint} ticket
+     * @returns {boolean}
+     */
+    isRoomClaimCurrent(room_id, ticket) {
+        const ret = wasm.subscriptiontracker_isRoomClaimCurrent(this.__wbg_ptr, room_id, ticket);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} room_id
+     * @returns {boolean}
+     */
+    isRoomSubscribed(room_id) {
+        const ret = wasm.subscriptiontracker_isRoomSubscribed(this.__wbg_ptr, room_id);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @returns {string[]}
+     */
+    joinedAgentTopics() {
+        const ret = wasm.subscriptiontracker_joinedAgentTopics(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * @param {any} topic
+     * @returns {bigint | undefined}
+     */
+    leaveAgentTopic(topic) {
+        const ret = wasm.subscriptiontracker_leaveAgentTopic(this.__wbg_ptr, topic);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return ret[0] === 0 ? undefined : BigInt.asUintN(64, ret[1]);
+    }
+    /**
+     * @param {any} topic
+     * @param {bigint} ticket
+     * @param {any} outcome
+     * @returns {boolean}
+     */
+    markAgentTopicLeaveComplete(topic, ticket, outcome) {
+        const ret = wasm.subscriptiontracker_markAgentTopicLeaveComplete(this.__wbg_ptr, topic, ticket, outcome);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} room_id
+     * @param {bigint} ticket
+     * @param {any} outcome
+     * @returns {boolean}
+     */
+    markRoomLeaveComplete(room_id, ticket, outcome) {
+        const ret = wasm.subscriptiontracker_markRoomLeaveComplete(this.__wbg_ptr, room_id, ticket, outcome);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    constructor() {
+        const ret = wasm.subscriptiontracker_new();
+        this.__wbg_ptr = ret;
+        SubscriptionTrackerFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    onReconnected() {
+        wasm.subscriptiontracker_onReconnected(this.__wbg_ptr);
+    }
+    /**
+     * @param {any} topic
+     * @param {bigint} ticket
+     * @param {boolean} joined
+     * @returns {boolean}
+     */
+    recordAgentTopicJoin(topic, ticket, joined) {
+        const ret = wasm.subscriptiontracker_recordAgentTopicJoin(this.__wbg_ptr, topic, ticket, joined);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} room_id
+     * @param {bigint} ticket
+     * @returns {string}
+     */
+    recordBothRoomTopicsJoined(room_id, ticket) {
+        const ret = wasm.subscriptiontracker_recordBothRoomTopicsJoined(this.__wbg_ptr, room_id, ticket);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return getStringFromWasm0(ret[0], ret[1]);
+    }
+    /**
+     * @param {any} room_id
+     * @param {bigint} ticket
+     * @returns {string}
+     */
+    recordChatRoomJoinFailed(room_id, ticket) {
+        const ret = wasm.subscriptiontracker_recordChatRoomJoinFailed(this.__wbg_ptr, room_id, ticket);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return getStringFromWasm0(ret[0], ret[1]);
+    }
+    /**
+     * @param {any} room_id
+     * @param {bigint} ticket
+     * @param {boolean} chatRoomLeft
+     * @returns {string}
+     */
+    recordRoomParticipantsJoinFailed(room_id, ticket, chatRoomLeft) {
+        const ret = wasm.subscriptiontracker_recordRoomParticipantsJoinFailed(this.__wbg_ptr, room_id, ticket, chatRoomLeft);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return getStringFromWasm0(ret[0], ret[1]);
+    }
+    /**
+     * @param {any} room_id
+     * @returns {string}
+     */
+    roomStatus(room_id) {
+        const ret = wasm.subscriptiontracker_roomStatus(this.__wbg_ptr, room_id);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return getStringFromWasm0(ret[0], ret[1]);
+    }
+    /**
+     * @returns {string[]}
+     */
+    subscribedRoomIds() {
+        const ret = wasm.subscriptiontracker_subscribedRoomIds(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * @param {any} room_id
+     * @returns {bigint | undefined}
+     */
+    unsubscribeRoom(room_id) {
+        const ret = wasm.subscriptiontracker_unsubscribeRoom(this.__wbg_ptr, room_id);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return ret[0] === 0 ? undefined : BigInt.asUintN(64, ret[1]);
+    }
+}
+if (Symbol.dispose) SubscriptionTracker.prototype[Symbol.dispose] = SubscriptionTracker.prototype.free;
+exports.SubscriptionTracker = SubscriptionTracker;
+
 /**
  * Validate and normalize an inbound platform event payload.
  *
@@ -650,6 +908,9 @@ const ParticipantRosterFinalization = (typeof FinalizationRegistry === 'undefine
 const RetryTrackerFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_retrytracker_free(ptr, 1));
+const SubscriptionTrackerFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_subscriptiontracker_free(ptr, 1));
 
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();

package/index.d.ts

@@ -145,3 +145,53 @@ export class ParticipantRoster {
   changed(): boolean;
   markSent(): void;
 }
+
+export type RoomSubscribeResult =
+  | "subscribed"
+  | "join_failed"
+  | "rolled_back"
+  | "rollback_failed"
+  | "stale";
+
+export type RoomStatus =
+  | "absent"
+  | "pending"
+  | "subscribed"
+  | "leaving"
+  | "needs_reconciliation";
+
+export type AgentTopicStatus =
+  | "absent"
+  | "pending"
+  | "joined"
+  | "leaving"
+  | "needs_reconciliation";
+
+export type LeaveOutcome = "left" | "failed" | "unknown";
+
+/** Transport-independent subscription decisions for one agent session. */
+export class SubscriptionTracker {
+  constructor();
+  beginRoomSubscribe(roomId: string): bigint | undefined;
+  recordChatRoomJoinFailed(roomId: string, ticket: bigint): RoomSubscribeResult;
+  recordBothRoomTopicsJoined(roomId: string, ticket: bigint): RoomSubscribeResult;
+  recordRoomParticipantsJoinFailed(roomId: string, ticket: bigint, chatRoomLeft: boolean): RoomSubscribeResult;
+  isRoomSubscribed(roomId: string): boolean;
+  isRoomClaimCurrent(roomId: string, ticket: bigint): boolean;
+  roomStatus(roomId: string): RoomStatus;
+  unsubscribeRoom(roomId: string): bigint | undefined;
+  markRoomLeaveComplete(roomId: string, ticket: bigint, outcome: LeaveOutcome): boolean;
+  acknowledgeRoomReconciled(roomId: string): boolean;
+  subscribedRoomIds(): string[];
+  onReconnected(): void;
+  endSession(): void;
+  beginAgentTopicJoin(topic: string): bigint | undefined;
+  recordAgentTopicJoin(topic: string, ticket: bigint, joined: boolean): boolean;
+  isAgentTopicJoined(topic: string): boolean;
+  isAgentTopicClaimCurrent(topic: string, ticket: bigint): boolean;
+  agentTopicStatus(topic: string): AgentTopicStatus;
+  leaveAgentTopic(topic: string): bigint | undefined;
+  markAgentTopicLeaveComplete(topic: string, ticket: bigint, outcome: LeaveOutcome): boolean;
+  acknowledgeAgentTopicReconciled(topic: string): boolean;
+  joinedAgentTopics(): string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@band-ai/band-sdk-core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Shared Band event-payload validation",
   "license": "MIT",
   "repository": {
@@ -10,7 +10,8 @@
   "files": [
     "band_sdk_core.js",
     "band_sdk_core_bg.wasm",
-    "index.d.ts"
+    "index.d.ts",
+    "README.md"
   ],
   "main": "./band_sdk_core.js",
   "types": "./index.d.ts",