@terminal3/t3n-sdk 0.8.0 → 0.11.0

package/README.md

@@ -586,7 +586,7 @@ To use the real WASM component:
 
    ```bash
    cd node
-   cargo build -p session --target wasm32-wasip2 --release
+   cargo build -p session-client --target wasm32-wasip2 --release
    ```
 
 2. **Copy the WASM file** to the SDK directory:

package/dist/index.d.ts

@@ -26,7 +26,9 @@ interface ClientHandshake {
      * Attempt to finalize handshake
      * @param state - Current handshake state
      * @returns Promise with session bytes if successful
-     * @throws Error if handshake not ready to finalize
+     * @throws Error containing "not yet finalized" if the state machine
+     *         has not reached its terminal phase. The SDK runtime treats
+     *         this as the loop's "keep going" signal, not a real error.
      */
     finish(state: Uint8Array): Promise<Uint8Array>;
 }
@@ -45,7 +47,9 @@ interface ClientAuth {
      * Attempt to finalize authentication
      * @param state - Current auth state
      * @returns Promise with DID bytes if successful
-     * @throws Error if authentication not ready to finalize
+     * @throws Error containing "not yet finalized" if the state machine
+     *         has not reached its terminal phase. The SDK runtime treats
+     *         this as the loop's "keep going" signal, not a real error.
      */
     finish(state: Uint8Array): Promise<Uint8Array>;
 }
@@ -64,7 +68,9 @@ interface ClientExecute {
      * Attempt to finalize authentication
      * @param state - Current auth state
      * @returns Promise with DID bytes if successful
-     * @throws Error if authentication not ready to finalize
+     * @throws Error containing "not yet finalized" if the state machine
+     *         has not reached its terminal phase. The SDK runtime treats
+     *         this as the loop's "keep going" signal, not a real error.
      */
     finish(state: Uint8Array): Promise<Uint8Array>;
 }
@@ -94,7 +100,7 @@ interface SessionCrypto {
  * authentication flows, and cryptographic operations are handled in WASM.
  */
 interface WasmComponent {
-    /** Client handshake operations */
+    /** Client-side state machines exported by the WASM component. */
     flow: {
         handshake: ClientHandshake;
         auth: ClientAuth;
@@ -518,7 +524,28 @@ declare class T3nClient {
     private readonly logger;
     private readonly encryption;
     private status;
+    /**
+     * In-flight WASM state-machine bytes. Holds the opaque state
+     * returned by `flow[method].next()` between iterations of
+     * `runFlow`. Always cleared at the top of `runFlow` and again
+     * once `tryFinalize` has extracted the terminal payload — so
+     * outside of an active loop these slots are always `null`.
+     */
     private wasmState;
+    /**
+     * Terminal payloads produced by `flow[method].finish()`:
+     * - `handshake` → serialized session blob, used by
+     *   `getSessionState()` for subsequent `session.encrypt` calls.
+     * - `auth` → serialized DID; the public `authenticate()` decodes
+     *   it into `this.did` and the slot is otherwise unused.
+     * - `execute` → unused (executes return immediately to the caller).
+     *
+     * Stored in a dedicated field instead of reusing `wasmState`
+     * because the two meanings — "in-flight state machine" vs
+     * "finalized payload" — are semantically different and merging
+     * them invites the bug-class Devin flagged in PR #1140.
+     */
+    private finalizedPayload;
     private did;
     private handshakeResult;
     constructor(config: T3nClientConfig);
@@ -559,11 +586,38 @@ declare class T3nClient {
     getLastResponseHeaders(): Record<string, string>;
     isAuthenticated(): boolean;
     /**
-     * Run a WASM state machine flow to completion
+     * Run a WASM state machine flow to completion.
+     *
+     * Clears both `wasmState[method]` and `finalizedPayload[method]`
+     * at entry so a flow that previously threw partway (e.g. an RPC
+     * error) starts from a clean slate on retry. Without the reset,
+     * stale state from the failed attempt leaks into the new flow
+     * and `tryFinalize` may either spuriously succeed or run `next()`
+     * against a state that no longer matches the action we're sending.
+     *
+     * The `tryFinalize`-then-`next` order is load-bearing: the loop's
+     * exit condition fires *after* the previous iteration's
+     * `handleWasmRequest` has flushed the outbound peer reply, so
+     * every state-machine emission reaches the wire before we extract
+     * the final payload.
      */
     private runFlow;
     /**
-     * Try to finalize the current flow
+     * Try to finalize the current flow. Returns the finish() payload
+     * (a serialized Session for handshake, a serialized DID for auth)
+     * or `null` if the state machine has not reached its terminal phase
+     * yet.
+     *
+     * The "not yet finalized" case is the loop's signal to keep
+     * iterating, not a real error. Any *other* failure must propagate
+     * so callers see real WASM errors instead of silent retries that
+     * spin forever.
+     *
+     * The terminal payload is stored in `finalizedPayload[method]`
+     * (a separate field from `wasmState[method]`) so the in-flight
+     * state-machine bytes and the finalized session/DID bytes never
+     * occupy the same slot. `getSessionState()` reads from
+     * `finalizedPayload.handshake`.
      */
     private tryFinalize;
     /**
@@ -584,7 +638,9 @@ declare class T3nClient {
      */
     private sendRpcRequest;
     /**
-     * Get the current session state for encryption
+     * Get the finalized session blob (for `session.encrypt` calls).
+     * Populated by `tryFinalize` once the handshake state machine
+     * reaches its terminal phase.
      */
     private getSessionState;
 }