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

package/README.md

@@ -107,6 +107,36 @@ switch (tracker.recordRoomParticipantsJoinFailed("room-1", ticket, false)) {
 }
 ```
 
+### `Session` — WebSocket reconnect state machine
+
+`Session`/`SessionPolicy` are a sans-io session state machine plus
+reconnect backoff/jitter policy; `classifyClose`/`classifyUpgrade`
+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.
+
+### `Session` lifecycle
+
+```ts
+import { Session, SessionPolicy } from "@band-ai/band-sdk-core";
+
+const session = new Session(SessionPolicy.default());
+const epoch = session.beginAttempt(0.0);
+if (epoch === undefined) throw new Error("fresh session must yield an epoch");
+
+const connected = session.onConnected(epoch, 0.0);
+if (connected.state !== "up") throw new Error("expected up");
+
+const disconnected = session.onSocketClose(epoch, 5.0, 1006, 0.5);
+if (disconnected.state !== "reconnecting") throw new Error("expected reconnecting");
+if (disconnected.retryAfterS === undefined) throw new Error("expected a retry delay");
+```
+
 ### `validateMemoryTypeForSystem(system, type, traceContext?)`
 
 Validates the canonical memory taxonomy — design decisions:

package/band_sdk_core.js

@@ -348,6 +348,410 @@ class RetryTracker {
 if (Symbol.dispose) RetryTracker.prototype[Symbol.dispose] = RetryTracker.prototype.free;
 exports.RetryTracker = RetryTracker;
 
+/**
+ * One reconnect's reconciliation against an authoritative room snapshot.
+ * `removed` and `admitting` are already applied by the time this is
+ * returned.
+ */
+class RoomReconciliation {
+    static __wrap(ptr) {
+        const obj = Object.create(RoomReconciliation.prototype);
+        obj.__wbg_ptr = ptr;
+        RoomReconciliationFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        RoomReconciliationFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_roomreconciliation_free(ptr, 0);
+    }
+    /**
+     * @returns {Array<any>}
+     */
+    get admitting() {
+        const ret = wasm.roomreconciliation_admitting(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {string[]}
+     */
+    get removed() {
+        const ret = wasm.roomreconciliation_removed(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * @returns {string[]}
+     */
+    get resync() {
+        const ret = wasm.roomreconciliation_resync(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+}
+if (Symbol.dispose) RoomReconciliation.prototype[Symbol.dispose] = RoomReconciliation.prototype.free;
+exports.RoomReconciliation = RoomReconciliation;
+
+/**
+ * Room admission and membership decisions for one agent session, separate
+ * from `SubscriptionTracker`'s two-topic transport join.
+ */
+class RoomRoster {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        RoomRosterFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_roomroster_free(ptr, 0);
+    }
+    /**
+     * @param {any} room_id
+     * @param {boolean} passesFilter
+     * @returns {bigint | undefined}
+     */
+    beginRoomAdmission(room_id, passesFilter) {
+        const ret = wasm.roomroster_beginRoomAdmission(this.__wbg_ptr, room_id, passesFilter);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return ret[0] === 0 ? undefined : BigInt.asUintN(64, ret[1]);
+    }
+    /**
+     * @returns {string[]}
+     */
+    clear() {
+        const ret = wasm.roomroster_clear(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
+     * @param {bigint} ticket
+     * @returns {boolean}
+     */
+    isRoomAdmissionCurrent(room_id, ticket) {
+        const ret = wasm.roomroster_isRoomAdmissionCurrent(this.__wbg_ptr, room_id, ticket);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    constructor() {
+        const ret = wasm.roomroster_new();
+        this.__wbg_ptr = ret;
+        RoomRosterFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * @param {any} current_room_ids
+     * @returns {RoomReconciliation}
+     */
+    reconcile(current_room_ids) {
+        const ret = wasm.roomroster_reconcile(this.__wbg_ptr, current_room_ids);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return RoomReconciliation.__wrap(ret[0]);
+    }
+    /**
+     * @param {any} room_id
+     * @param {bigint} ticket
+     * @param {boolean} succeeded
+     * @returns {boolean}
+     */
+    recordRoomAdmission(room_id, ticket, succeeded) {
+        const ret = wasm.roomroster_recordRoomAdmission(this.__wbg_ptr, room_id, ticket, succeeded);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} room_id
+     * @returns {boolean}
+     */
+    recordRoomRemoved(room_id) {
+        const ret = wasm.roomroster_recordRoomRemoved(this.__wbg_ptr, room_id);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * @param {any} room_id
+     * @returns {string}
+     */
+    roomMembership(room_id) {
+        const ret = wasm.roomroster_roomMembership(this.__wbg_ptr, room_id);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return getStringFromWasm0(ret[0], ret[1]);
+    }
+    /**
+     * @returns {string[]}
+     */
+    trackedRoomIds() {
+        const ret = wasm.roomroster_trackedRoomIds(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+}
+if (Symbol.dispose) RoomRoster.prototype[Symbol.dispose] = RoomRoster.prototype.free;
+exports.RoomRoster = RoomRoster;
+
+/**
+ * One WebSocket session's state machine. Behavior contract:
+ * `docs/runtime-state-policy.md`'s `## Session` section.
+ */
+class Session {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        SessionFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_session_free(ptr, 0);
+    }
+    /**
+     * @param {number} nowS
+     * @returns {bigint | undefined}
+     */
+    beginAttempt(nowS) {
+        const ret = wasm.session_beginAttempt(this.__wbg_ptr, nowS);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        return ret[0] === 0 ? undefined : BigInt.asUintN(64, ret[1]);
+    }
+    /**
+     * @returns {string}
+     */
+    end() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.session_end(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * @param {SessionPolicy} policy
+     */
+    constructor(policy) {
+        _assertClass(policy, SessionPolicy);
+        const ret = wasm.session_new(policy.__wbg_ptr);
+        this.__wbg_ptr = ret;
+        SessionFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * @param {bigint} epoch
+     * @param {number} nowS
+     * @returns {SessionOutcome}
+     */
+    onConnected(epoch, nowS) {
+        const ret = wasm.session_onConnected(this.__wbg_ptr, epoch, nowS);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return SessionOutcome.__wrap(ret[0]);
+    }
+    /**
+     * @param {bigint} epoch
+     * @param {number} nowS
+     * @param {number | null | undefined} closeCode
+     * @param {number} jitterSample
+     * @returns {SessionOutcome}
+     */
+    onSocketClose(epoch, nowS, closeCode, jitterSample) {
+        const ret = wasm.session_onSocketClose(this.__wbg_ptr, epoch, nowS, !isLikeNone(closeCode), isLikeNone(closeCode) ? 0 : closeCode, jitterSample);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return SessionOutcome.__wrap(ret[0]);
+    }
+    /**
+     * @param {number} nowS
+     * @param {boolean} retryable
+     * @param {number | null | undefined} retryAfterS
+     * @param {number} jitterSample
+     * @returns {SessionOutcome}
+     */
+    onSupersede(nowS, retryable, retryAfterS, jitterSample) {
+        const ret = wasm.session_onSupersede(this.__wbg_ptr, nowS, retryable, !isLikeNone(retryAfterS), isLikeNone(retryAfterS) ? 0 : retryAfterS, jitterSample);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return SessionOutcome.__wrap(ret[0]);
+    }
+    /**
+     * @param {bigint} epoch
+     * @param {number} nowS
+     * @param {number} status
+     * @param {number | null | undefined} retryAfterS
+     * @param {number} jitterSample
+     * @returns {SessionOutcome}
+     */
+    onUpgradeRejected(epoch, nowS, status, retryAfterS, jitterSample) {
+        const ret = wasm.session_onUpgradeRejected(this.__wbg_ptr, epoch, nowS, status, !isLikeNone(retryAfterS), isLikeNone(retryAfterS) ? 0 : retryAfterS, jitterSample);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return SessionOutcome.__wrap(ret[0]);
+    }
+    /**
+     * @returns {string}
+     */
+    get state() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.session_state(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) Session.prototype[Symbol.dispose] = Session.prototype.free;
+exports.Session = Session;
+
+/**
+ * The settled outcome of one `Session` call.
+ */
+class SessionOutcome {
+    static __wrap(ptr) {
+        const obj = Object.create(SessionOutcome.prototype);
+        obj.__wbg_ptr = ptr;
+        SessionOutcomeFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        SessionOutcomeFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_sessionoutcome_free(ptr, 0);
+    }
+    /**
+     * @returns {string | undefined}
+     */
+    get deadReason() {
+        const ret = wasm.sessionoutcome_deadReason(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 {number | undefined}
+     */
+    get retryAfterS() {
+        const ret = wasm.sessionoutcome_retryAfterS(this.__wbg_ptr);
+        return ret[0] === 0 ? undefined : ret[1];
+    }
+    /**
+     * @returns {boolean}
+     */
+    get stale() {
+        const ret = wasm.sessionoutcome_stale(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * @returns {string}
+     */
+    get state() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.sessionoutcome_state(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) SessionOutcome.prototype[Symbol.dispose] = SessionOutcome.prototype.free;
+exports.SessionOutcome = SessionOutcome;
+
+/**
+ * Reconnect backoff/jitter policy, plus the graduated rapid-disconnect
+ * cooldown ladder. Behavior contract: `docs/runtime-state-policy.md`'s
+ * `## Session` section.
+ */
+class SessionPolicy {
+    static __wrap(ptr) {
+        const obj = Object.create(SessionPolicy.prototype);
+        obj.__wbg_ptr = ptr;
+        SessionPolicyFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        SessionPolicyFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_sessionpolicy_free(ptr, 0);
+    }
+    /**
+     * A recommended, not final, default.
+     * @returns {SessionPolicy}
+     */
+    static default() {
+        const ret = wasm.sessionpolicy_default();
+        return SessionPolicy.__wrap(ret);
+    }
+    /**
+     * `config` is any plain object with the fields declared in
+     * `index.d.ts`'s `SessionPolicyConfig`; grouped into one value rather
+     * than a flat, many-argument constructor.
+     * @param {any} config
+     * @param {any} traceContext
+     */
+    constructor(config, traceContext) {
+        const ret = wasm.sessionpolicy_new(config, traceContext);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0];
+        SessionPolicyFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+}
+if (Symbol.dispose) SessionPolicy.prototype[Symbol.dispose] = SessionPolicy.prototype.free;
+exports.SessionPolicy = SessionPolicy;
+
 /**
  * Transport-independent subscription decisions for one agent session.
  */
@@ -606,6 +1010,35 @@ class SubscriptionTracker {
 if (Symbol.dispose) SubscriptionTracker.prototype[Symbol.dispose] = SubscriptionTracker.prototype.free;
 exports.SubscriptionTracker = SubscriptionTracker;
 
+/**
+ * Classify a WebSocket close code. Returns `[terminal, delayRange]`.
+ * @param {number | null} [closeCode]
+ * @returns {Array<any>}
+ */
+function classifyClose(closeCode) {
+    const ret = wasm.classifyClose(!isLikeNone(closeCode), isLikeNone(closeCode) ? 0 : closeCode);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.classifyClose = classifyClose;
+
+/**
+ * Classify an HTTP upgrade-rejection status code. Returns
+ * `[terminal, delayRange]`.
+ * @param {number} status
+ * @returns {Array<any>}
+ */
+function classifyUpgrade(status) {
+    const ret = wasm.classifyUpgrade(status);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.classifyUpgrade = classifyUpgrade;
+
 /**
  * Validate and normalize an inbound platform event payload.
  *
@@ -744,6 +1177,10 @@ function __wbg_get_imports() {
             const ret = Object.entries(arg0);
             return ret;
         },
+        __wbg_get_971a0c45d172643f: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.get(arg0, arg1);
+            return ret;
+        }, arguments); },
         __wbg_get_c0c8f8d7da0c03dd: function(arg0, arg1) {
             const ret = arg0[arg1 >>> 0];
             return ret;
@@ -908,6 +1345,21 @@ const ParticipantRosterFinalization = (typeof FinalizationRegistry === 'undefine
 const RetryTrackerFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_retrytracker_free(ptr, 1));
+const RoomReconciliationFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_roomreconciliation_free(ptr, 1));
+const RoomRosterFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_roomroster_free(ptr, 1));
+const SessionFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_session_free(ptr, 1));
+const SessionOutcomeFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_sessionoutcome_free(ptr, 1));
+const SessionPolicyFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_sessionpolicy_free(ptr, 1));
 const SubscriptionTrackerFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_subscriptiontracker_free(ptr, 1));
@@ -918,6 +1370,12 @@ function addToExternrefTable0(obj) {
     return idx;
 }
 
+function _assertClass(instance, klass) {
+    if (!(instance instanceof klass)) {
+        throw new Error(`expected instance of ${klass.name}`);
+    }
+}
+
 function debugString(val) {
     // primitive types
     const type = typeof val;

package/index.d.ts

@@ -169,6 +169,110 @@ export type AgentTopicStatus =
 
 export type LeaveOutcome = "left" | "failed" | "unknown";
 
+export type SessionState = "connecting" | "up" | "reconnecting" | "dead";
+
+export type DeadReason = "classified" | "rapid_disconnect";
+
+export type RoomMembership = "unadmitted" | "admitting" | "admitted";
+
+/**
+ * Classify a WebSocket close code. Returns `[terminal, delayRange]`.
+ * Throws a plain `Error` if `closeCode` is not an integer in `0..=65535`
+ * (or `undefined`).
+ */
+export function classifyClose(
+  closeCode: number | undefined,
+): [boolean, [number, number] | undefined];
+
+/**
+ * Classify an HTTP upgrade-rejection status code. Returns
+ * `[terminal, delayRange]`. Throws a plain `Error` if `status` is not an
+ * integer in `0..=65535`.
+ */
+export function classifyUpgrade(
+  status: number,
+): [boolean, [number, number] | undefined];
+
+/** The settled outcome of one {@link Session} call. */
+export class SessionOutcome {
+  private constructor();
+  readonly state: SessionState;
+  readonly retryAfterS: number | undefined;
+  readonly deadReason: DeadReason | undefined;
+  readonly stale: boolean;
+}
+
+/** {@link SessionPolicy}'s constructor fields. */
+export interface SessionPolicyConfig {
+  baseDelayS: number;
+  factor: number;
+  maxDelayS: number;
+  stableResetS: number;
+  rapidDisconnectUptimeS: number;
+  rapidWindowS: number;
+  rapidFirstMinDelayS: number;
+  rapidSecondMinDelayS: number;
+  rapidCooldownBaseS: number;
+  rapidCooldownStepS: number;
+  rapidCooldownMaxS: number;
+  rapidThreshold: number;
+}
+
+/**
+ * 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.
+ *
+ * Throws a native `Error` with `.issues`/`.traceContext` if `factor < 1.0`
+ * or `baseDelayS > maxDelayS`. Throws a plain `Error` if `config` is
+ * missing a field or a field is not a finite, non-negative number
+ * (`rapidThreshold` must also be an integer).
+ */
+export class SessionPolicy {
+  constructor(config: SessionPolicyConfig, traceContext?: string | null);
+  /** A recommended, not final, default. */
+  static default(): SessionPolicy;
+}
+
+/**
+ * One WebSocket session's state machine: which epoch (connection attempt)
+ * is live, the current lifecycle state, and the reconnect/rapid-disconnect
+ * bookkeeping. Single-writer -- exactly one owner drives a given `Session`
+ * at a time.
+ *
+ * `nowS`/`retryAfterS` each throw a plain `Error` if not a finite,
+ * non-negative number; `jitterSample` throws unless it's a finite number
+ * in `[0.0, 1.0]` (a fraction, not an open-ended time value);
+ * `closeCode`/`status` throw if not an integer in `0..=65535` (or
+ * `undefined` for `closeCode`).
+ */
+export class Session {
+  constructor(policy: SessionPolicy);
+  readonly state: SessionState;
+  beginAttempt(nowS: number): bigint | undefined;
+  onConnected(epoch: bigint, nowS: number): SessionOutcome;
+  onSocketClose(
+    epoch: bigint,
+    nowS: number,
+    closeCode: number | undefined,
+    jitterSample: number,
+  ): SessionOutcome;
+  onUpgradeRejected(
+    epoch: bigint,
+    nowS: number,
+    status: number,
+    retryAfterS: number | undefined,
+    jitterSample: number,
+  ): SessionOutcome;
+  onSupersede(
+    nowS: number,
+    retryable: boolean,
+    retryAfterS: number | undefined,
+    jitterSample: number,
+  ): SessionOutcome;
+  end(): SessionState;
+}
+
 /** Transport-independent subscription decisions for one agent session. */
 export class SubscriptionTracker {
   constructor();
@@ -195,3 +299,35 @@ export class SubscriptionTracker {
   acknowledgeAgentTopicReconciled(topic: string): boolean;
   joinedAgentTopics(): string[];
 }
+
+/**
+ * One reconnect's reconciliation against an authoritative room snapshot.
+ * `removed` and `admitting` are already applied by the time this is
+ * returned.
+ */
+export class RoomReconciliation {
+  private constructor();
+  readonly removed: string[];
+  readonly admitting: Array<[string, bigint]>;
+  readonly resync: string[];
+}
+
+/**
+ * Room admission and membership decisions for one agent session, separate
+ * from {@link SubscriptionTracker}'s two-topic transport join.
+ *
+ * Every `roomId` argument below throws a plain `Error` if it is not a
+ * string. `reconcile` throws a plain `Error` if `currentRoomIds` is not an
+ * array of strings.
+ */
+export class RoomRoster {
+  constructor();
+  roomMembership(roomId: string): RoomMembership;
+  beginRoomAdmission(roomId: string, passesFilter: boolean): bigint | undefined;
+  recordRoomAdmission(roomId: string, ticket: bigint, succeeded: boolean): boolean;
+  isRoomAdmissionCurrent(roomId: string, ticket: bigint): boolean;
+  recordRoomRemoved(roomId: string): boolean;
+  trackedRoomIds(): string[];
+  reconcile(currentRoomIds: string[]): RoomReconciliation;
+  clear(): string[];
+}

package/package.json

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