@terminal3/t3n-sdk 0.8.0 → 0.11.0

package/dist/src/client/t3n-client.d.ts

@@ -16,7 +16,28 @@ export 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);
@@ -57,11 +78,38 @@ export 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;
     /**
@@ -82,7 +130,9 @@ export 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;
 }

package/dist/src/wasm/interface.d.ts

@@ -26,7 +26,9 @@ export 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 @@ export 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 @@ export 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 @@ export interface SessionCrypto {
  * authentication flows, and cryptographic operations are handled in WASM.
  */
 export interface WasmComponent {
-    /** Client handshake operations */
+    /** Client-side state machines exported by the WASM component. */
     flow: {
         handshake: ClientHandshake;
         auth: ClientAuth;

package/dist/wasm/generated/session.d.ts

@@ -6,8 +6,6 @@ export type * as WasiIoError029 from './interfaces/wasi-io-error.js'; // import
 export type * as WasiIoStreams029 from './interfaces/wasi-io-streams.js'; // import wasi:io/streams@0.2.9
 export type * as WasiRandomRandom029 from './interfaces/wasi-random-random.js'; // import wasi:random/random@0.2.9
 export * as clientAuth from './interfaces/component-session-client-auth.js'; // export component:session/client-auth@0.1.0
-export * as serverAuth from './interfaces/component-session-server-auth.js'; // export component:session/server-auth@0.1.0
 export * as clientHandshake from './interfaces/component-session-client-handshake.js'; // export component:session/client-handshake@0.1.0
-export * as serverHandshake from './interfaces/component-session-server-handshake.js'; // export component:session/server-handshake@0.1.0
 export * as session from './interfaces/component-session-session.js'; // export component:session/session@0.1.0
 export * as cookie from './interfaces/component-session-cookie.js'; // export component:session/cookie@0.1.0