@band-ai/band-sdk-core 1.0.0 → 1.1.0

package/README.md

@@ -55,8 +55,8 @@ 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).
+inbound-delivery runtime state classes — lifecycle and design decisions
+live as rustdoc on each type in `crates/core/src/runtime/`.
 
 A participant is any plain object; `add`/`setAll` read `id`, `name`,
 `type`, `handle`, `description` from it and `list()` returns objects with
@@ -115,10 +115,8 @@ classify a WebSocket close code or HTTP upgrade-rejection status.
 `Session` never sleeps, connects, or closes a socket itself — the caller
 drives its own transport and reports what happened through `onConnected`/
 `onSocketClose`/`onUpgradeRejected`/`onSupersede`. Its epoch tickets are
-JavaScript `bigint` values, matching `SubscriptionTracker`'s. Confirmed
-decisions:
-[`runtime-state-policy.md`](https://github.com/band-ai/band-sdk-core/blob/main/crates/core/docs/runtime-state-policy.md)'s
-`## Session` section.
+JavaScript `bigint` values, matching `SubscriptionTracker`'s. Decisions
+live as rustdoc in `crates/core/src/runtime/session.rs`.
 
 ### `Session` lifecycle
 
@@ -139,8 +137,8 @@ if (disconnected.retryAfterS === undefined) throw new Error("expected a retry de
 
 ### `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).
+Validates the canonical memory taxonomy — design decisions live as
+rustdoc in `crates/core/src/memory.rs`.
 `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

package/band_sdk_core.js

@@ -513,8 +513,7 @@ if (Symbol.dispose) RoomRoster.prototype[Symbol.dispose] = RoomRoster.prototype.
 exports.RoomRoster = RoomRoster;
 
 /**
- * One WebSocket session's state machine. Behavior contract:
- * `docs/runtime-state-policy.md`'s `## Session` section.
+ * One WebSocket session's state machine.
  */
 class Session {
     __destroy_into_raw() {
@@ -677,11 +676,16 @@ class SessionOutcome {
         return ret[0] === 0 ? undefined : ret[1];
     }
     /**
-     * @returns {boolean}
+     * @returns {string | undefined}
      */
-    get stale() {
-        const ret = wasm.sessionoutcome_stale(this.__wbg_ptr);
-        return ret !== 0;
+    get staleReason() {
+        const ret = wasm.sessionoutcome_staleReason(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;
     }
     /**
      * @returns {string}
@@ -704,8 +708,7 @@ exports.SessionOutcome = SessionOutcome;
 
 /**
  * Reconnect backoff/jitter policy, plus the graduated rapid-disconnect
- * cooldown ladder. Behavior contract: `docs/runtime-state-policy.md`'s
- * `## Session` section.
+ * cooldown ladder.
  */
 class SessionPolicy {
     static __wrap(ptr) {
@@ -903,6 +906,17 @@ class SubscriptionTracker {
         }
         return ret[0] !== 0;
     }
+    /**
+     * @param {any} topic
+     * @returns {boolean}
+     */
+    markAgentTopicRejoinFailed(topic) {
+        const ret = wasm.subscriptiontracker_markAgentTopicRejoinFailed(this.__wbg_ptr, topic);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
     /**
      * @param {any} room_id
      * @param {bigint} ticket
@@ -916,6 +930,17 @@ class SubscriptionTracker {
         }
         return ret[0] !== 0;
     }
+    /**
+     * @param {any} room_id
+     * @returns {boolean}
+     */
+    markRoomRejoinFailed(room_id) {
+        const ret = wasm.subscriptiontracker_markRoomRejoinFailed(this.__wbg_ptr, room_id);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
     constructor() {
         const ret = wasm.subscriptiontracker_new();
         this.__wbg_ptr = ret;

package/index.d.ts

@@ -173,6 +173,12 @@ export type SessionState = "connecting" | "up" | "reconnecting" | "dead";
 
 export type DeadReason = "classified" | "rapid_disconnect";
 
+export type StaleReason =
+  | "wrong_epoch"
+  | "clock_regression"
+  | "duplicate_connected"
+  | "supersede_predates_epoch";
+
 export type RoomMembership = "unadmitted" | "admitting" | "admitted";
 
 /**
@@ -199,7 +205,7 @@ export class SessionOutcome {
   readonly state: SessionState;
   readonly retryAfterS: number | undefined;
   readonly deadReason: DeadReason | undefined;
-  readonly stale: boolean;
+  readonly staleReason: StaleReason | undefined;
 }
 
 /** {@link SessionPolicy}'s constructor fields. */
@@ -220,8 +226,7 @@ export interface SessionPolicyConfig {
 
 /**
  * Reconnect backoff/jitter policy, plus the graduated rapid-disconnect
- * cooldown ladder. A recommended, not final, starting design -- see
- * `docs/runtime-state-policy.md`'s `## Session` section.
+ * cooldown ladder. A recommended, not final, starting design.
  *
  * Throws a native `Error` with `.issues`/`.traceContext` if `factor < 1.0`
  * or `baseDelayS > maxDelayS`. Throws a plain `Error` if `config` is
@@ -286,6 +291,7 @@ export class SubscriptionTracker {
   unsubscribeRoom(roomId: string): bigint | undefined;
   markRoomLeaveComplete(roomId: string, ticket: bigint, outcome: LeaveOutcome): boolean;
   acknowledgeRoomReconciled(roomId: string): boolean;
+  markRoomRejoinFailed(roomId: string): boolean;
   subscribedRoomIds(): string[];
   onReconnected(): void;
   endSession(): void;
@@ -297,6 +303,7 @@ export class SubscriptionTracker {
   leaveAgentTopic(topic: string): bigint | undefined;
   markAgentTopicLeaveComplete(topic: string, ticket: bigint, outcome: LeaveOutcome): boolean;
   acknowledgeAgentTopicReconciled(topic: string): boolean;
+  markAgentTopicRejoinFailed(topic: string): boolean;
   joinedAgentTopics(): string[];
 }
 

package/package.json

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