@ibgib/core-gib 0.1.59 → 0.1.60

package/src/sync/docs/security-3b.md

@@ -0,0 +1,92 @@
+# Implementation Plan: Phase 3B — Basic Single-Timeline Sync with Identity (Integrated)
+
+This document outlines the implementation plan for Phase 3B of identity integration, focusing on integrating the cryptographic session identity into the WebSocket sync peer architecture, and wiring up the Row 3B dev-tools test buttons.
+
+## 1. Goal
+The goal of Phase 3B is to achieve successful end-to-end synchronization of a test ibgib `X` over a stateful WebSocket connection using asymmetric session identity validation. 
+At the end of the sync saga:
+- Both sender and receiver durable spaces must contain the same evolved Domain Keystone (I1).
+- Both spaces must contain the full session identity keystone (S) graph evolved to the correct turn count ($n = 3$, or potentially $n = 4$ depending on exact commit phase timeline evolution).
+- Both spaces must contain the identical target ibgib `X` dependency graph.
+
+---
+
+## 2. Technical Challenge: Asymmetric Authentication in WebSocket Peers
+In V1, only the sender (Alice) signs the synchronization context. The receiver (Bob) skips signing the response context (`skipSign: true`), relying on transport-level security (TLS) for the return path. 
+Consequently:
+- Alice's request context contains a `signedSessionIdentity`.
+- Bob's response context has `signedSessionIdentity` set to `undefined`.
+
+### Current Issue in `SyncPeerWebSocketSender_V1`
+In `SyncPeerWebSocketSender_V1.handleRuntimeMessage`, the sender currently attempts to authenticate Bob's response context:
+```typescript
+if (msg.type === SyncWebSocketMsgType.sync_frame_response) {
+    const responseContext = msg.context as SyncSagaContextIbGib_V1;
+
+    // Validate and authenticate Bob's response context first
+    await this.authenticateAndValidate({ context: responseContext });
+```
+Because `authenticateAndValidate` calls `authenticateContextIntrinsically` which expects a signature when `sagaFrame.data.sessionIdentityTjpAddr` is present, this call will throw an error since Bob's response context has no `signedSessionIdentity`.
+
+### Solution
+Change `SyncPeerWebSocketSender_V1.handleRuntimeMessage` to run structural/intrinsic validation instead of full authentication on the response context:
+```typescript
+// Ensure the response context and saga frame are valid structurally
+const validationErrors = await validateContextAndSagaFrame({ context: responseContext });
+if (validationErrors.length > 0) {
+    throw new Error(`Invalid response context received. Errors: ${validationErrors.join(', ')}`);
+}
+```
+The client-side `SyncSagaCoordinator` will then run the turn-by-turn continuation, sequence, and identity validation checks via `validateReturnContext(...)`. This provides a robust stopgap validation for V1 before the receiver-side signing is fully implemented in future versions.
+
+
+---
+
+## 3. UI Integration: Dev Tools Row 3B
+We will wire up the three buttons in `apps/space-gib/src/client/dev-tools.mts` under the `init3bPlaceholder` placeholder handler:
+
+### 3.1. `btn-3b-setup`
+- **Actions**:
+  1. Generates a new long-lived Domain Keystone (I) for Alice using master secret `'test-sender-secret-phase3'` and unique salts (`'senderidentitysyncsaltphase3'`, `'senderidentitymanagesaltphase3'`).
+  2. Registers the genesis Domain Keystone (I) on the server via `apiBridge.postGenesisKeystone(domainI)`.
+  3. Creates a local dummy Target IbGib (X) with distinct test data: `{ hello: 'world3', random: Math.random() }`.
+  4. Stores `domainI`, `domainIMasterSecret`, and `targetX` in `debugState`.
+  5. Updates button text to `✓ 3B Setup Complete` and enables `btn-3b-sync`.
+
+### 3.2. `btn-3b-sync`
+- **Actions**:
+  1. Instantiates `SyncPeerWebSocketSender_V1` targeting the server's WS and evolution endpoints.
+  2. Initializes peer options with Alice's identity, secret, and a newly generated `sagaId`.
+  3. Instantiates `SyncSagaCoordinator`.
+  4. Calls `coordinator.sync(...)` to synchronize Target X to the server.
+  5. Awaits completion (`await syncSaga.done`). This must run without errors.
+  6. Updates button text to `✓ 3B Sync Run` and enables `btn-3b-check`.
+
+### 3.3. `btn-3b-check`
+- **Actions**:
+  1. Resolves the client's latest Target X address and fetches its local dependency graph.
+  2. Resolves the server's latest Target X address and fetches its server-side dependency graph using a new API bridge helper.
+  3. Asserts the client and server Target X graphs are equivalent:
+     - The latest address of X is identical.
+     - Graph node counts are identical.
+     - All keys and values match.
+  4. Resolves the latest session identity (S) address and asserts it evolved to `n = 2` (Init at $n=0$, Connect Handshake at $n=1$, Sync Context Sign at $n=2$).
+  5. Verifies the latest S address and graph are identical on both client and server.
+  6. Verifies the evolved Domain Keystone (I1) is present in both client and server spaces.
+  7. If all checks pass, logs `🎉 ALL PHASE 3B CHECKS PASSED FLAWLESSLY! ✓` and updates button text to `✓ 3B All Passed`.
+
+---
+
+## 4. Concrete Checklist
+
+### [ ] API Bridge Extension
+- [ ] Add `getIbGibGraph(domainAddr, ibGibAddr)` to `SpaceGibApiBridge` (`apps/space-gib/src/client/api/space-gib-api-bridge.mts`) to retrieve dependency graphs with `getGraph=true`.
+
+### [ ] WebSocket Peer Adjustments
+- [ ] Modify `SyncPeerWebSocketSender_V1.handleRuntimeMessage` to bypass `authenticateAndValidate` on Bob's response context, using `validateContextAndSagaFrame` instead.
+
+### [ ] Dev Tools UI (Row 3B) Wiring
+- [ ] Implement `init3bSetupButton` inside `dev-tools.mts`.
+- [ ] Implement `init3bSyncButton` inside `dev-tools.mts`.
+- [ ] Implement `init3bCheckButton` inside `dev-tools.mts`.
+- [ ] Update `initDevTools` to initialize the new button handlers and remove `init3bPlaceholder`.

package/src/sync/docs/security.md

@@ -285,29 +285,29 @@ We still call `senderCoordinator.sync(...)` — the phase focus is on what `peer
 
 **Goal**: With identity fully established and transport connected, sync a single ibgib `X` from source to dest. Verify S evolves correctly per turn (`sync` pool), and X's full dependency graph arrives on dest. After commit, both sender and receiver durable spaces must contain: the same evolved I, the full S dependency graph, and the full X dependency graph.
 
-#### Phase 3A — Innerspace unit test (`sync-withid.fullsync.respec.mts`)
-
-- [ ] Create `sync-withid.fullsync.respec.mts`
-  - [ ] Create `r1_alpha_v0_source` via `TestTransformer`
-  - [ ] Call `senderCoordinator.sync({ domainIbGibs: [alpha], senderIdentity, senderSecret, ... })`
-  - [ ] `ifWeMight` — `"alpha dep graph matches on source and dest"`: use `getDependencyGraph` + `graphsAreEquivalent`
-  - [ ] `ifWeMight` — `"sessionIdentity evolved the expected number of times"`: assert `S.data.n` equals the known deterministic turn count
-    - [ ] 🔲 **TODO**: Manually inspect the full session keystone graph after a first run and count the exact number of outgoing turns (Init + Delta(s) + Commit), then hard-code that number into this assertion
-  - [ ] `ifWeMight` — `"sender durable space has I (evolved frame)"`: assert I1 addr is in `sourceSpace`
-  - [ ] `ifWeMight` — `"receiver durable space has I (evolved frame)"`: assert I1 addr is in `destSpace`
-  - [ ] `ifWeMight` — `"sender durable space has full S dep graph"`: use `getDependencyGraph` on S in `sourceSpace`
-  - [ ] `ifWeMight` — `"receiver durable space has full S dep graph"`: use `getDependencyGraph` on S in `destSpace`
+#### Phase 3A — Innerspace unit test (`sync-withid.pingpong.respec.mts`)
+
+- [x] Create `sync-withid.pingpong.respec.mts`
+  - [x] Create `r1_alpha_v0_source` (represented by `xStone` test domain ibgib)
+  - [x] Call `senderCoordinator.sync({ domainIbGibs: [alpha], senderIdentity, senderSecret, ... })`
+  - [x] `ifWeMight` — `"alpha dep graph matches on source and dest"`: use `getDependencyGraph` + `graphsAreEquivalent`
+  - [x] `ifWeMight` — `"sessionIdentity evolved the expected number of times"`: assert `S.data.n` equals the known deterministic turn count
+    - [x] ☑ **TODO**: Manually inspect the full session keystone graph after a first run and count the exact number of outgoing turns (Init + Delta(s) + Commit), then hard-code that number into this assertion
+  - [x] `ifWeMight` — `"sender durable space has I (evolved frame)"`: assert I1 addr is in `sourceSpace`
+  - [x] `ifWeMight` — `"receiver durable space has I (evolved frame)"`: assert I1 addr is in `destSpace`
+  - [x] `ifWeMight` — `"sender durable space has full S dep graph"`: use `getDependencyGraph` on S in `sourceSpace`
+  - [x] `ifWeMight` — `"receiver durable space has full S dep graph"`: use `getDependencyGraph` on S in `destSpace`
 
 #### Phase 3B — Space-Gib integrated (manual)
 
-- [ ] Trigger a sync of a known test ibgib via `dev-tools.mts` (add "sync - fullsync" button to a new row)
-- [ ] Confirm S evolves on each outgoing turn (inspect frame `data.n` in debugger)
-- [ ] Confirm X's full dependency graph is present on the client after commit
-- [ ] Confirm X's full dependency graph is present on the server after commit
-- [ ] Confirm S's full dependency graph is present on the client after commit
-- [ ] Confirm S's full dependency graph is present on the server after commit
-- [ ] Confirm I's evolved frame (I1) is present on the client after commit
-- [ ] Confirm I's evolved frame (I1) is present on the server after commit
+- [x] Trigger a sync of a known test ibgib via `dev-tools.mts` (add "sync - fullsync" button to a new row)
+- [x] Confirm S evolves on each outgoing turn (inspect frame `data.n` in debugger)
+- [x] Confirm X's full dependency graph is present on the client after commit
+- [x] Confirm X's full dependency graph is present on the server after commit
+- [x] Confirm S's full dependency graph is present on the client after commit
+- [x] Confirm S's full dependency graph is present on the server after commit
+- [x] Confirm I's evolved frame (I1) is present on the client after commit
+- [x] Confirm I's evolved frame (I1) is present on the server after commit
 
 
 ---
@@ -320,14 +320,14 @@ The sync proper will not be called. The test only cares that the pre-connect ide
 
 #### Phase 1A — Innerspace unit test
 
-- [ ] Create `sync-with-identity-basic.respec.mts` with scaffold:
+- [x] Create `sync-withid.establish.respec.mts` with scaffold:
   - `Metaspace_Innerspace` + two `InnerSpace_V1` (source/dest) + `SyncSagaCoordinator` pair + `newTestPeer()` factory
   - A `senderSecret` constant (test-only plaintext)
   - A `KeystoneService_V1` instance (new'd inline)
-- [ ] Add `respecfully` block: `"Phase 1: establishSessionIdentity"`
-  - [ ] `ifWeMight` — `"creates sessionIdentity genesis (S) locally"`: assert `S^Stjp` was generated and exists in `sourceSpace`
-  - [ ] `ifWeMight` — `"evolves senderIdentity (I → I1) with sync claim"`: assert `I1` frame has a proof whose `claim.verb === 'sync'` and `claim.target === S^Stjp`
-  - [ ] `ifWeMight` — `"posts I1 and S to destSpace (receiver)"`: assert both addrs are retrievable from `destSpace`
+- [x] Add `respecfully` block: `"Phase 1: establishSessionIdentity"`
+  - [x] `ifWeMight` — `"creates sessionIdentity genesis (S) locally"`: assert `S^Stjp` was generated and exists in `sourceSpace`
+  - [x] `ifWeMight` — `"evolves senderIdentity (I → I1) with sync claim"`: assert `I1` frame has a proof whose `claim.verb === 'sync'` and `claim.target === S^Stjp`
+  - [x] `ifWeMight` — `"posts I1 and S to destSpace (receiver)"`: assert both addrs are retrievable from `destSpace`
 
 #### Phase 1B — Space-Gib integrated (manual)
 
@@ -344,7 +344,7 @@ The sync proper will not be called. The test only cares that the pre-connect ide
 
 #### Phase 2A — Innerspace unit test
 
-- [x] Extend `sync-with-identity-basic.respec.mts` with a `respecfully` block: `"Phase 2: connect"` (Note: implemented in separate file `sync-withid.connect.respec.mts`)
+- [x] Create `sync-withid.connect.respec.mts` with a `respecfully` block: `"Phase 2: connect"`
   - [x] `ifWeMight` — `"connect completes without error"`: call `peer.connect()` and assert no exception
   - [x] `ifWeMight` — `"connect pool is depleted by exactly one challenge"`: assert `S.data.pools['connect'].used` increased by the expected count
 
@@ -362,19 +362,87 @@ The sync proper will not be called. The test only cares that the pre-connect ide
 
 #### Phase 3A — Innerspace unit test
 
-- [ ] Extend `sync-with-identity-basic.respec.mts` or create `sync-with-identity-singletimeline.respec.mts`
-  - [ ] Create `r1_alpha_v0_source` via `TestTransformer`
-  - [ ] Call `senderCoordinator.sync({ domainIbGibs: [alpha], senderIdentity, senderSecret, ... })`
-  - [ ] `ifWeMight` — `"alpha dep graph matches on source and dest"`: use `getDependencyGraph` + `graphsAreEquivalent`
-  - [ ] `ifWeMight` — `"sessionIdentity evolved once per sync turn"`: assert `S.data.n` equals number of outgoing turns
+- [x] Create `sync-withid.pingpong.respec.mts`
+  - [x] Create `r1_alpha_v0_source` via `TestTransformer` (represented by `xStone` test domain ibgib)
+  - [x] Call `senderCoordinator.sync({ domainIbGibs: [alpha], senderIdentity, senderSecret, ... })`
+  - [x] `ifWeMight` — `"alpha dep graph matches on source and dest"`: use `getDependencyGraph` + `graphsAreEquivalent`
+  - [x] `ifWeMight` — `"sessionIdentity evolved once per sync turn"`: assert `S.data.n` equals number of outgoing turns
 
 #### Phase 3B — Space-Gib integrated (manual)
 
-- [ ] Trigger a sync of a known test ibgib via `dev-tools.mts` or equivalent UI
-- [ ] Confirm S evolves on each outgoing turn (inspect frame `data.n` in debugger)
-- [ ] Confirm X's full dependency graph is present on the client after commit
-- [ ] Confirm X's full dependency graph is present on the server after commit
-- [ ] Confirm S's full dependency graph is present on the client after commit
-- [ ] Confirm S's full dependency graph is present on the server after commit
-- [ ] Confirm I's full dependency graph is present on the client after commit
-- [ ] Confirm I's full dependency graph is present on the server after commit
+- [x] Trigger a sync of a known test ibgib via `dev-tools.mts` or equivalent UI
+- [x] Confirm S evolves on each outgoing turn (inspect frame `data.n` in debugger)
+- [x] Confirm X's full dependency graph is present on the client after commit
+- [x] Confirm X's full dependency graph is present on the server after commit
+- [x] Confirm S's full dependency graph is present on the client after commit
+- [x] Confirm S's full dependency graph is present on the server after commit
+- [x] Confirm I's full dependency graph is present on the client after commit
+- [x] Confirm I's full dependency graph is present on the server after commit
+
+---
+
+### Phase 4 — Advanced Data and Conflict Scenarios
+
+**Goal**: Extend the WebSocket peer and Space-Gib interface to manually execute and verify all advanced data and conflict scenarios currently covered by the InnerSpace unit tests.
+
+For each scenario, verify automated innerspace tests (A) are fully functional, and create manual websocket peer tests (B) with corresponding buttons/UI elements.
+
+#### 1. Sync InnerSpace (Basic Push Sync)
+- [ ] Phase 4.1A — Automated InnerSpace Verification (`sync-innerspace.respec.mts`)
+- [ ] Phase 4.1B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests basic push sync of a single timeline and its mutations from Source to Destination.
+  * Verifies that the target timeline tip and its dependency graph successfully arrive at the destination.
+
+#### 2. Sync Constants (No TJP)
+- [ ] Phase 4.2A — Automated InnerSpace Verification (`sync-innerspace-constants.respec.mts`)
+- [ ] Phase 4.2B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests syncing "constants" (ibGibs without timelines/TJPs) and verifies that dependencies (linked constants) are resolved.
+  * Ensures idempotency/smart diffing (payloads are not re-sent if they already exist in the destination space).
+
+#### 3. Sync Destination with Partial History
+- [ ] Phase 4.3A — Automated InnerSpace Verification (`sync-innerspace-partial-update.respec.mts`)
+- [ ] Phase 4.3B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests push synchronization when the destination already contains a partial timeline history (e.g., up to V1), but the sender has newer frames (V2).
+  * Verifies that only the delta is transmitted and correctly linked to the existing history at the destination.
+
+#### 4. Sync Deep History Updates
+- [ ] Phase 4.4A — Automated InnerSpace Verification (`sync-innerspace-deep-updates.respec.mts`)
+- [ ] Phase 4.4B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests push synchronization of a timeline tip with a deep mutation history (multiple updates).
+  * Verifies that the destination receives all intermediate frames, preserving the full timeline history and graph integrity.
+
+#### 5. Sync Destination Ahead (Remote Newer)
+- [ ] Phase 4.5A — Automated InnerSpace Verification (`sync-innerspace-dest-ahead.respec.mts`)
+- [ ] Phase 4.5B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests synchronization when the destination (remote) actually has a newer frame (V2) than the sender's local tip (V1).
+  * Verifies that the sender learns of the remote tip and pulls it down so both client and server converge to the dest-ahead tip.
+
+#### 6. Sync Multiple Independent Timelines
+- [ ] Phase 4.6A — Automated InnerSpace Verification (`sync-innerspace-multiple-timelines.respec.mts`)
+- [ ] Phase 4.6B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests synchronization of multiple independent timelines (e.g., Timeline A and Timeline B) in a single sync coordinator call.
+  * Verifies that both timeline tips and their respective dependency graphs are transferred and updated correctly.
+
+#### 7. Basic Divergence Conflict Resolution
+- [ ] Phase 4.7A — Automated InnerSpace Verification (`sync-conflict-basic-divergence.respec.mts`)
+- [ ] Phase 4.7B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests divergence when source and destination edit different fields on a shared base timeline simultaneously.
+  * Verifies that optimistic merge automatically produces a merged tip (V3) containing both edits and records the graft metadata (`graftbase`, `graftorphan`).
+
+#### 8. Divergence with Related Timelines
+- [ ] Phase 4.8A — Automated InnerSpace Verification (`sync-conflict-basic-multitimelines.respec.mts`)
+- [ ] Phase 4.8B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests advanced divergence where one of the divergent updates also references/relates a new independent timeline (Beta).
+  * Verifies that during optimistic merge, the dependent timeline is synced automatically alongside the merged tip.
+
+#### 9. Text Field Merge (LCS) Conflict Resolution
+- [ ] Phase 4.9A — Automated InnerSpace Verification (`sync-conflict-text-merge.respec.mts`)
+- [ ] Phase 4.9B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests automatic merging of conflicting string edits within the `ibgib.data.text` field using the LCS (Longest Common Subsequence) merge algorithm.
+  * Verifies merging of simple appends (beginning vs. end) and interleaved edits in different paragraphs.
+
+#### 10. Advanced Multi-Round/Timeline Permutations
+- [ ] Phase 4.10A — Automated InnerSpace Verification (`sync-conflict-adv-multitimelines.respec.mts`)
+- [ ] Phase 4.10B — WebSocket Peer Manual Verification (integrated via Dev Tools)
+  * Tests complex multi-round/timeline permutations with parallel divergent edits across multiple rounds.
+  * Verifies that nested or sequential merges resolve correctly using the optimistic graft strategy.

package/src/sync/sync-peer/sync-peer-innerspace/sync-peer-innerspace-v1.mts

@@ -325,7 +325,7 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<ConnectSyncPeerInnerspace
             if (!msgResponse.data) { throw new Error(`(UNEXPECTED) sync saga message ibgib.data falsy? (E: 61ec18743988ad3cbab2072d1dd69826)`); }
 
             const responsePayloadIbGibsControl = [
-                msgResponse, responseCtx.sagaFrame, context
+                msgResponse, responseCtx.sagaFrame, responseCtx
             ].map(x => toDto({ ibGib: x }));
             // ...put into sender's durable space
             await putInSpace({

package/src/sync/sync-peer/sync-peer-types.mts

@@ -198,7 +198,17 @@ export interface SyncPeerWitness<TInitializeOpts extends InitializeSyncPeerOpts
     // getSenderIdentity(): KeystoneIbGib_V1 | undefined;
 
     /**
-     * Evolves the session identity (S_n -> S_n+1) and signs targeting contextAddr.
+     * Evolves the session identity (S_n -> S_n+1) and signs targeting
+     * contextAddr for the **sync** verb. This is in contrast to signing for
+     * the "connect" verb, for which you use {@link signContextConnect}
      */
     signContext(opts: { contextAddr: IbGibAddr }): Promise<KeystoneIbGib_V1 | undefined>;
+
+    /**
+     * Evolves the session identity (S_n -> S_n+1) solving the demanded connect
+     * challenges.  This is NOT for signing session when doing the ping pong of
+     * sync protocol. For that, you use {@link signContext}
+     */
+    signContextConnect(opts: { challengeUuid: string, demandedIds: string[] }): Promise<KeystoneIbGib_V1 | undefined>;
+
 }

package/src/sync/sync-peer/sync-peer-v1.mts

@@ -23,7 +23,7 @@ import { getFullSyncSagaHistory, deriveSessionSecret } from '../sync-helpers.mjs
 import { SessionGenesisFrameDetails, SyncSagaFrameDependencyGraph } from '../sync-types.mjs';
 import { KeystoneService_V1 } from '../../keystone/keystone-service-v1.mjs';
 import { KeystoneIbGib_V1 } from '../../keystone/keystone-types.mjs';
-import { KEYSTONE_VERB_SYNC, } from '../../keystone/keystone-constants.mjs';
+import { KEYSTONE_VERB_CONNECT, KEYSTONE_VERB_SYNC, POOL_ID_CONNECT, } from '../../keystone/keystone-constants.mjs';
 import { getTjpAddr } from '../../common/other/ibgib-helper.mjs';
 import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 
@@ -99,6 +99,52 @@ export abstract class SyncPeer_V1<
         }
     }
 
+    /**
+ * Evolves the session identity (S_n -> S_n+1) solving the demanded connect challenges.
+ */
+    public async signContextConnect({
+        challengeUuid,
+        demandedIds,
+    }: {
+        challengeUuid: string;
+        demandedIds: string[];
+    }): Promise<KeystoneIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.signContextConnect.name}]`;
+        try {
+            if (!this.currentSessionIdentity) {
+                return undefined;
+            }
+            if (!this.opts) { throw new Error(`opts not initialized. (E: bcf5978aed789b0ebcbdc51971ebe826)`); }
+            const { fnSenderSecret, sagaId, localMetaspace, localSpace } = this.opts;
+            if (!fnSenderSecret) { throw new Error(`fnSenderSecret not initialized. (E: 207fd292a2e8c53c05fd0a74a4ae6d26)`); }
+            if (!sagaId) { throw new Error(`sagaId not initialized. (E: f2e35cc13ed873b638116188119d1826)`); }
+
+            const senderSecret = await fnSenderSecret();
+            const sessionSecret = await deriveSessionSecret({ senderSecret, sagaId });
+
+            const keystoneSvc = new KeystoneService_V1();
+            const evolved = await keystoneSvc.sign({
+                latestKeystone: this.currentSessionIdentity,
+                masterSecret: sessionSecret,
+                poolId: POOL_ID_CONNECT,
+                requiredChallengeIds: demandedIds,
+                claim: {
+                    verb: KEYSTONE_VERB_CONNECT,
+                    target: challengeUuid,
+                },
+                metaspace: localMetaspace,
+                space: localSpace,
+            });
+
+            this.currentSessionIdentity = evolved;
+            return evolved;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
+
     get classname(): string {
         if (!this.data) { throw new Error(`(UNEXPECTED) this.data falsy? (E: 1ab1841e9338b54f3aa615fa37024826)`); }
         if (!this.data.classname) { throw new Error(`invalid peer. this.data.classname is falsy (E: b0ee28a0abb84a06588d9de7afcef826)`); }

package/src/sync/sync-peer/sync-peer-websocket/README.md

@@ -0,0 +1,42 @@
+# WebSocket Sync Peers
+
+This directory contains the WebSocket client (sender) and server (receiver) peer implementations.
+
+## WebSocket Resource Management & Teardown
+
+Since WebSockets manage active OS-level TCP connections, they must be cleanly closed to prevent socket descriptor leaks on the client and resource exhaustion (DoS) on the server.
+
+### Analysis (2026-06-12T09:45:21-05:00)
+
+Our analysis highlights several areas where WebSocket connections are currently left open:
+
+1. **Sender Connect Failures**: If connection handshake fails or times out, the client rejects the promise but does not close the socket.
+2. **Sender Runtime Failures**: If runtime message validation fails, we throw an error but leave the socket open.
+3. **Sender Saga Completion**: When the sync loop finishes successfully, the socket is left open indefinitely because there is no `disconnect` method.
+4. **Receiver Message Handling Failures**: If incoming messages fail validation/authentication, the server sends a `sync_error` or `auth_fail` frame, but relies on the client to close the connection. A buggy/malicious client can leave it open forever.
+
+#### Design Questions & Ideas
+* **Idempotent `disconnect()`**: The disconnect method on the sender should clear `this.handshakeMessageListener` and set it to `undefined` so that multiple calls to `disconnect()` are safe.
+* **Reuse `disconnect()`**: In connection failure handlers (like `handleHandshakeAuthFail`), we can call `this.disconnect()` to ensure uniform cleanup.
+* **Server-side Close on Error (best-effort `send`)**: If a message fails, we want to notify the client first and then close the connection. If the `send()` itself throws, we want a safe cleanup. In JavaScript, we can nest `try..catch..finally` inside a `catch` block, or use a short `setTimeout` to push the socket close operation to the next event loop tick, ensuring the outgoing frame is written before the socket is terminated.
+
+---
+
+### Implementation TODOs
+
+- [x] **Implement `disconnect` method on `SyncPeerWebSocketSender_V1`**
+  - Implement a synchronous or asynchronous `disconnect()` method.
+  - Safely remove the message event listener `this.handshakeMessageListener`.
+  - Set `this.handshakeMessageListener = undefined` to make it idempotent.
+  - Close the WebSocket `this.ws.close()`.
+  
+- [x] **Clean up socket on Sender connection failures**
+  - Call `this.disconnect()` inside `handleHandshakeAuthFail`.
+  - Call `this.disconnect()` inside `handleHandshakeSyncError`.
+  
+- [x] **Close socket on Sender runtime message validation failures**
+  - In `handleRuntimeMessage` and `handleRuntimeSyncFrameResponse`, catch validation errors, trigger `this.disconnect()`, and rethrow.
+
+- [x] **Close socket on Receiver message handling failures**
+  - In the catch block of `handleIncomingMessage`, call `this.socketWrapper?.close()` (or equivalent wrapper cleanup) to force-close connections after sending error frames.
+  - Wrap the `send()` call in a nested try/catch or use `setTimeout` to ensure best-effort message transmission before terminating the socket wrapper.

package/src/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-peer-websocket-receiver-v1.mts

@@ -34,6 +34,7 @@ export interface IWebSocketWrapper {
     send(data: string): void;
     onMessage(callback: (data: string) => void): void;
     onClose(callback: () => void): void;
+    close(): void;
 }
 
 /**
@@ -213,7 +214,8 @@ export class SyncPeerWebSocketReceiver_V1
                 // First, validate and authenticate the context
                 const allControlIbGibs: IbGib_V1[] = [
                     toDto({ ibGib: context }),
-                    context.sagaFrame
+                    context.sagaFrame,
+                    context.sagaFrameMsg
                 ];
                 if (context.signedSessionIdentity) {
                     allControlIbGibs.push(context.signedSessionIdentity);
@@ -262,10 +264,16 @@ export class SyncPeerWebSocketReceiver_V1
             }
         } catch (error) {
             console.error(`${lc} message frame handling failed: ${extractErrorMsg(error)}`);
-            this.socketWrapper?.send(JSON.stringify({
-                type: this.isAuthenticated ? SyncWebSocketMsgType.sync_error : SyncWebSocketMsgType.auth_fail,
-                message: extractErrorMsg(error)
-            }));
+            try {
+                this.socketWrapper?.send(JSON.stringify({
+                    type: this.isAuthenticated ? SyncWebSocketMsgType.sync_error : SyncWebSocketMsgType.auth_fail,
+                    message: extractErrorMsg(error)
+                }));
+            } catch (nestedError) {
+                console.error(`${lc}[nested catch] failed to send error frame: ${extractErrorMsg(nestedError)}`);
+            } finally {
+                this.socketWrapper?.close();
+            }
         }
     }
 
@@ -327,6 +335,7 @@ export class SyncPeerWebSocketReceiver_V1
 
             // Persist the newly validated evolved session keystone tip
             await metaspace.put({ ibGibs: [proofFrame], space });
+            await metaspace.registerNewIbGib({ ibGib: proofFrame, space });
 
             if (logalot) { console.log(`${lc} connect validation successful! Connection upgraded to active sync session.`); }
             this.isAuthenticated = true;