@ibgib/core-gib 0.1.55 → 0.1.58

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

@@ -9,6 +9,7 @@ import { SyncSagaContextData_V1, SyncSagaContextIbGib_V1, SyncSagaContextRel8ns_
 import { Witness_V1 } from '../../witness/witness-types.mjs';
 import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
 import { MetaspaceService } from '../../witness/space/metaspace/metaspace-types.mjs';
+import { KeystoneIbGib_V1, KeystonePoolConfig } from '../../keystone/keystone-types.mjs';
 
 /**
  * Data for the SyncPeer witness.
@@ -36,13 +37,29 @@ export interface SyncPeerIbGib_V1 extends IbGib_V1<SyncPeerData_V1, SyncPeerRel8
  * opts used in `connect(opts)`
  */
 export interface ConnectSyncPeerOpts {
+    /**
+     * TODO: sagaId is now also on {@link InitializeSyncPeerOpts} since a peer
+     * is scoped to a single sync saga. Evaluate whether this duplicate is still
+     * needed when implementing the connect phase (Phase 2).
+     */
     sagaId: string;
 }
 
 /**
- * base initialization opts
+ * base initialization opts.
+ *
+ * A sync peer is scoped to exactly one sync saga. A new peer instance must be
+ * created for each `sync(...)` call. Reusing a peer across multiple sagas is
+ * not supported and would compromise the identity security model.
  */
 export interface InitializeSyncPeerOpts {
+    /**
+     * Unique id for the sync saga this peer is servicing.
+     * Generated by `SyncSagaCoordinator.sync()` and passed here so that
+     * `establishSessionIdentity` can derive the session secret via
+     * `KDF(senderSecret, sagaId)`.
+     */
+    sagaId?: string;
     /**
      * reference to the local metaspace
      */
@@ -62,6 +79,44 @@ export interface InitializeSyncPeerOpts {
      * received/created throughout the transaction until commit.
      */
     localTempSpace?: IbGibSpaceAny;
+    /**
+     * The sender's long-lived Domain Keystone (I) — Alice's identity.
+     * Optional; if omitted the sync runs without identity (anonymous).
+     * Must be the current tip frame of I's timeline.
+     *
+     * Both {@link senderIdentity} and {@link fnSenderSecret} must be provided
+     * together or omitted together.
+     */
+    senderIdentity?: KeystoneIbGib_V1;
+    /**
+     * Returns the plaintext secret corresponding to {@link senderIdentity}.
+     * Wrapped in a function to avoid holding the secret in memory longer than needed.
+     *
+     * Both {@link senderIdentity} and {@link fnSenderSecret} must be provided
+     * together or omitted together.
+     */
+    fnSenderSecret?: () => Promise<string>;
+    /**
+     * Pool config for the session keystone's transport connect handshake pool.
+     * Required when {@link senderIdentity} is provided.
+     *
+     * @see {@link POOL_ID_CONNECT}
+     */
+    sessionConnectPoolConfig?: KeystonePoolConfig;
+    /**
+     * Pool config for the session keystone's per-turn signing pool (`sync`).
+     * Required when {@link senderIdentity} is provided.
+     *
+     * @see {@link POOL_ID_SYNC}
+     */
+    sessionSyncPoolConfig?: KeystonePoolConfig;
+    /**
+     * Addresses of the synced domains (ibgibs).
+     * Used during `establishSessionIdentity` to bind the session keystone (S)
+     * strictly to these domains, preventing S from acting as a "blank check"
+     * for unauthorized domains.
+     */
+    targetAddrs?: string[];
 }
 
 /**
@@ -107,6 +162,20 @@ export interface SyncPeerWitness<TInitializeOpts extends InitializeSyncPeerOpts
      */
     payloadIbGibsDomainReceived$: SubjectWitness<IbGib_V1>;
 
+    /**
+     * Pre-connect phase: creates the session keystone (S) locally, evolves
+     * `senderIdentity` (I → I1) with a `sync` claim targeting S, and posts
+     * both to the receiver's domain registry.
+     *
+     * Must be called before `connect()`. No-op if `senderIdentity` was not
+     * provided in {@link InitializeSyncPeerOpts}.
+     *
+     * @returns The session keystone genesis (S^Stjp). The coordinator holds
+     * this reference for the remainder of the saga. The name `newSenderIdentity`
+     * (I1) is intentionally scoped only within this method to avoid confusion.
+     */
+    establishSessionIdentity(): Promise<KeystoneIbGib_V1 | undefined>;
+
     /**
      * Establishes the connection context.
      *

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

@@ -23,8 +23,11 @@ import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
 import { newupSubject } from '../../common/pubsub/subject/subject-helper.mjs';
 import { authenticateContext, authorizeContext, validateContextAndSagaFrame } from '../sync-saga-context/sync-saga-context-helpers.mjs';
 import { getFromSpace } from '../../witness/space/space-helper.mjs';
-import { getFullSyncSagaHistory } from '../sync-helpers.mjs';
+import { getFullSyncSagaHistory, deriveSessionSecret } from '../sync-helpers.mjs';
 import { 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';
 
 const logalot = GLOBAL_LOG_A_LOT;
 const logalotControlDomain = false;
@@ -107,6 +110,96 @@ export abstract class SyncPeer_V1<
      */
     protected abstract connectImpl(opts: TConnectOpts): Promise<void>;
 
+    /**
+     * Pre-connect phase: establishes session identity.
+     *
+     * Shared base implementation:
+     * 1. Derives `sessionSecret = KDF(senderSecret, sagaId)`.
+     * 2. Creates session keystone genesis S (connect + sync pools) in `localSpace`.
+     * 3. Evolves `senderIdentity` → `newSenderIdentity` (I1) with a `sync`
+     *    claim targeting S^Stjp, stored in `localSpace`.
+     * 4. Delegates posting of both keystones to the receiver via the abstract
+     *    hook {@link postEstablishToReceiver} (peer-specific transport).
+     *
+     * Returns `undefined` (no-op) if no `senderIdentity` was provided in opts.
+     *
+     * @returns The session keystone genesis (S^Stjp) so the coordinator can
+     * hold a reference for subsequent per-turn signing. The name
+     * `newSenderIdentity` (I1) is scoped only within this method.
+     */
+    public async establishSessionIdentity(): Promise<KeystoneIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.establishSessionIdentity.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: f2a1b3c4d5e6f7a8b9c0d1e2f3a4b526)`); }
+
+            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? Call initializeOpts first. (E: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c526)`); }
+
+            const { senderIdentity, fnSenderSecret, sagaId, localMetaspace, localSpace } = this.opts;
+
+            // No identity provided — anonymous sync, nothing to establish.
+            if (!senderIdentity || !fnSenderSecret) {
+                if (logalot) { console.log(`${lc} no senderIdentity/fnSenderSecret — skipping establish (I: f29348a77d1542326d14043ea4b69126)`); }
+                return undefined;
+            }
+
+            if (!sagaId) { throw new Error(`(UNEXPECTED) sagaId falsy? Must be set in initializeOpts before calling establishSessionIdentity. (E: c6ba389d51b8af07d82458f875cf9826)`); }
+
+            const senderSecret = await fnSenderSecret();
+            if (!senderSecret) { throw new Error(`senderSecret falsy. senderSecret required. (E: 1a8b0298bf78cbdf284b7988983b9826)`); }
+            const sessionSecret = await deriveSessionSecret({ senderSecret, sagaId });
+
+            const keystoneSvc = new KeystoneService_V1();
+
+            // Step 1: Create S genesis in localSpace.
+            // Pool configs must be provided via opts (set by coordinator before calling establish).
+            if (!this.opts.sessionConnectPoolConfig) { throw new Error(`(UNEXPECTED) opts.sessionConnectPoolConfig falsy? (E: 3351fd566eb8bbd2f821bb08c4419826)`); }
+            if (!this.opts.sessionSyncPoolConfig) { throw new Error(`(UNEXPECTED) opts.sessionSyncPoolConfig falsy? (E: dbffa810d9e7ff6079088deb5b8e7826)`); }
+
+            const sessionIdentity = await keystoneSvc.genesis({
+                masterSecret: sessionSecret,
+                configs: [this.opts.sessionConnectPoolConfig, this.opts.sessionSyncPoolConfig],
+                frameDetails: this.opts.targetAddrs ? { targetAddrs: this.opts.targetAddrs } : undefined,
+                metaspace: localMetaspace,
+                space: localSpace,
+            });
+            const sessionIdentityAddr = getIbGibAddr({ ibGib: sessionIdentity });
+
+            // Step 2: Evolve senderIdentity → newSenderIdentity (I1) with sync claim.
+            const newSenderIdentity = await keystoneSvc.sign({
+                latestKeystone: senderIdentity,
+                masterSecret: senderSecret,
+                claim: {
+                    verb: KEYSTONE_VERB_SYNC,
+                    target: sessionIdentityAddr,
+                },
+                metaspace: localMetaspace,
+                space: localSpace,
+            });
+
+            // Step 3: Post both to the receiver (peer-specific).
+            await this.postEstablishToReceiver({ newSenderIdentity, sessionIdentity });
+
+            return sessionIdentity;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Peer-specific hook: transmits `newSenderIdentity` (I1) and
+     * `sessionIdentity` (S) to the receiver's domain registry.
+     *
+     * - **Innerspace**: puts both into `receiverMetaspace` / `receiverSpace`.
+     * - **WebSocket**: HTTP POST to the domain provider's keystone endpoint.
+     */
+    protected abstract postEstablishToReceiver(opts: {
+        newSenderIdentity: KeystoneIbGib_V1;
+        sessionIdentity: KeystoneIbGib_V1;
+    }): Promise<void>;
+
     /**
      * base implementation just sets the opts property.
      *

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

@@ -0,0 +1,36 @@
+/**
+ * @module sync-peer-websocket-receiver-types
+ */
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import {
+    SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWitness,
+    InitializeSyncPeerOpts, ConnectSyncPeerOpts
+} from '../sync-peer-types.mjs';
+import { SyncSagaCoordinator } from '../../sync-saga-coordinator.mjs';
+
+/**
+ * Data for the SyncPeerWebSocketReceiver witness.
+ */
+export interface SyncPeerWebSocketReceiverData_V1 extends SyncPeerData_V1 {
+}
+
+/**
+ * Relations for the SyncPeerWebSocketReceiver witness.
+ */
+export interface SyncPeerWebSocketReceiverRel8ns_V1 extends SyncPeerRel8ns_V1 {
+}
+
+/**
+ * The SyncPeerWebSocketReceiver witness IbGib.
+ */
+export interface SyncPeerWebSocketReceiverIbGib_V1 extends IbGib_V1<SyncPeerWebSocketReceiverData_V1, SyncPeerWebSocketReceiverRel8ns_V1> { }
+
+export interface ConnectSyncPeerWebSocketReceiverOpts extends ConnectSyncPeerOpts {
+}
+
+export interface InitializeSyncPeerWebSocketReceiverOpts extends InitializeSyncPeerOpts {
+    /**
+     * The local SyncSagaCoordinator instance running on the receiver/server.
+     */
+    localCoordinator: SyncSagaCoordinator;
+}

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

@@ -0,0 +1,337 @@
+/**
+ * @module sync-peer-websocket-receiver-v1
+ */
+
+import { extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+import { SyncPeer_V1 } from '../sync-peer-v1.mjs';
+import { SyncSagaContextIbGib_V1 } from '../../sync-saga-context/sync-saga-context-types.mjs';
+import { authenticateContext } from '../../sync-saga-context/sync-saga-context-helpers.mjs';
+import { IbGibSpaceAny } from '../../../witness/space/space-base-v1.mjs';
+import { putInSpace, registerNewIbGib } from '../../../witness/space/space-helper.mjs';
+import {
+    ConnectSyncPeerWebSocketReceiverOpts,
+    InitializeSyncPeerWebSocketReceiverOpts,
+    SyncPeerWebSocketReceiverData_V1, SyncPeerWebSocketReceiverRel8ns_V1,
+    SyncPeerWebSocketReceiverIbGib_V1
+} from './sync-peer-websocket-receiver-types.mjs';
+import { KeystoneIbGib_V1 } from '../../../keystone/keystone-types.mjs';
+import { SESSION_KEYSTONE_POLICY, verifyConnectProof } from './sync-websocket-peer-helpers.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+/**
+ * A platform-agnostic interface wrapping runtime-specific WebSocket stream operations.
+ */
+export interface IWebSocketWrapper {
+    send(data: string): void;
+    onMessage(callback: (data: string) => void): void;
+    onClose(callback: () => void): void;
+}
+
+/**
+ * Platform-agnostic WebSocket Receiver Peer.
+ *
+ * Fully encapsulates the multi-turn cryptographic challenge connect and runtime
+ * turn routing.
+ */
+export class SyncPeerWebSocketReceiver_V1
+    extends SyncPeer_V1<ConnectSyncPeerWebSocketReceiverOpts, InitializeSyncPeerWebSocketReceiverOpts>
+    implements SyncPeerWebSocketReceiverIbGib_V1 {
+
+    protected override lc: string = `[${SyncPeerWebSocketReceiver_V1.name}]`;
+
+    override get classname(): string {
+        return SyncPeerWebSocketReceiver_V1.name;
+    }
+
+    declare data: SyncPeerWebSocketReceiverData_V1 | undefined;
+    declare rel8ns: SyncPeerWebSocketReceiverRel8ns_V1 | undefined;
+
+    protected socketWrapper?: IWebSocketWrapper;
+
+    // Connect State Machine variables
+    protected isAuthenticated = false;
+    protected challengeUuid?: string;
+    protected demandedIds?: string[];
+    protected sessionS_tjpAddr?: string;
+
+    constructor(
+        initialData: SyncPeerWebSocketReceiverData_V1,
+        initialRel8ns?: SyncPeerWebSocketReceiverRel8ns_V1,
+    ) {
+        super(initialData, initialRel8ns);
+    }
+
+    /**
+     * Wires the peer receiver to the platform-specific socket stream and
+     * triggers the connect.
+     */
+    public async bindSocket(socketWrapper: IWebSocketWrapper): Promise<void> {
+        const lc = `${this.lc}[${this.bindSocket.name}]`;
+        this.socketWrapper = socketWrapper;
+        socketWrapper.onMessage((data) => this.handleIncomingMessage(data));
+
+        // Immediately trigger multi-turn challenge connection
+        try {
+            this.challengeUuid = await getUUID();
+            socketWrapper.send(JSON.stringify({
+                type: 'auth-challenge-init',
+                challengeUuid: this.challengeUuid
+            }));
+        } catch (error) {
+            console.error(`${lc} failed triggering challenge init: ${extractErrorMsg(error)}`);
+            socketWrapper.send(JSON.stringify({
+                type: 'auth-fail',
+                message: 'Internal server connect error'
+            }));
+        }
+    }
+
+    protected override async preConnectCheck(opts: ConnectSyncPeerWebSocketReceiverOpts): Promise<void> {
+        // Handled dynamically on upgrade
+    }
+
+    protected override async connectImpl(opts: ConnectSyncPeerWebSocketReceiverOpts): Promise<void> {
+        // Handled dynamically on upgrade
+    }
+
+    protected override async postEstablishToReceiver(opts: {
+        newSenderIdentity: KeystoneIbGib_V1;
+        sessionIdentity: KeystoneIbGib_V1;
+    }): Promise<void> {
+        throw new Error(`postEstablishToReceiver is not supported on Receiver Peer (E: 309f3cf8e7c813d338394f28c576da26)`);
+    }
+
+    protected override async sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
+        throw new Error(`sendContextRequest is not supported on Receiver Peer (E: e5327ed6c64883e12ef95984f1409926)`);
+    }
+
+    /** Helper to load a Session Keystone from storage */
+    protected async getSessionKeystone(sAddr: string): Promise<KeystoneIbGib_V1> {
+        const metaspace = this.opts!.localMetaspace;
+        const space = this.opts!.localSpace;
+        const resGet = await metaspace.get({ addrs: [sAddr], space });
+        if (resGet.success && resGet.ibGibs && resGet.ibGibs.length === 1) {
+            return resGet.ibGibs[0] as KeystoneIbGib_V1;
+        }
+        throw new Error(`Session keystone not found in storage: ${sAddr} (E: 42315837e3b1deb5b81072f8601e6a26)`);
+    }
+
+    protected async ensureLocalTempSpace(): Promise<IbGibSpaceAny> {
+        const lc = `${this.lc}[${this.ensureLocalTempSpace.name}]`;
+        try {
+            if (!this.opts) { throw new Error(`opts not initialized. (E: c4929fb1596833a7186d119855bb7e26)`); }
+
+            if (!this.opts.localTempSpace) {
+                const { localMetaspace } = this.opts;
+
+                const uuid = crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36);
+                const tempSpaceName = `tmp_sync_recv_${uuid.substring(0, 8)}`;
+                const localTempSpace = await localMetaspace.createNewLocalSpace({
+                    opts: {
+                        allowCancel: false,
+                        spaceName: tempSpaceName,
+                        getFnPrompt: localMetaspace.getFnPrompt!,
+                        logalot
+                    }
+                });
+                if (!localTempSpace) { throw new Error(`couldn't create a temp space (E: d82461769b4bbb35df5d6a8a9c665426)`); }
+                await localTempSpace.initialized;
+                this.opts.localTempSpace = localTempSpace;
+            }
+
+            return this.opts.localTempSpace;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Entry point for processing raw text frames received over the active WebSocket connection.
+     */
+    public async handleIncomingMessage(messageText: string): Promise<void> {
+        const lc = `${this.lc}[${this.handleIncomingMessage.name}]`;
+        try {
+            if (!this.socketWrapper) {
+                throw new Error(`WebSocket wrapper not bound to receiver peer (E: ad4c5838d1b87259586b21a89b2c7726)`);
+            }
+
+            const msg = JSON.parse(messageText);
+            if (logalot) { console.log(`${lc} received frame: ${msg.type}`); }
+
+            // 1. Connect Phase Route Guard
+            if (!this.isAuthenticated) {
+                await this.handleConnectFrame(msg);
+                return; /* <<<< returns early */
+            }
+
+            // 2. Authenticated Runtime Sync Route
+            if (msg.type === 'domain-payload') {
+                const ibGib = msg.ibGib as IbGib_V1;
+                const tempSpace = await this.ensureLocalTempSpace();
+                await putInSpace({ space: tempSpace, ibGibs: [ibGib] });
+            } else if (msg.type === 'sync-frame') {
+                const context = msg.context as SyncSagaContextIbGib_V1;
+
+                // Process turn through coordinator
+                const responseCtx = await this.handleIncomingSyncRequest({ context });
+
+                if (responseCtx) {
+                    // Send outgoing payload domain ibgibs first
+                    const responsePayloads = responseCtx.payloadIbGibsDomain ?? [];
+                    for (const ibGib of responsePayloads) {
+                        this.socketWrapper.send(JSON.stringify({
+                            type: 'domain-payload',
+                            ibGib
+                        }));
+                    }
+
+                    // Send evolved context turn response
+                    this.socketWrapper.send(JSON.stringify({
+                        type: 'sync-frame-response',
+                        context: responseCtx
+                    }));
+                } else {
+                    if (logalot) { console.log(`${lc} synchronization session completed successfully.`); }
+                }
+            }
+        } catch (error) {
+            console.error(`${lc} message frame handling failed: ${extractErrorMsg(error)}`);
+            this.socketWrapper?.send(JSON.stringify({
+                type: this.isAuthenticated ? 'sync-error' : 'auth-fail',
+                message: extractErrorMsg(error)
+            }));
+        }
+    }
+
+    /**
+     * Handles the multi-turn cryptographic challenge connect messages.
+     */
+    protected async handleConnectFrame(msg: any): Promise<void> {
+        const lc = `${this.lc}[${this.handleConnectFrame.name}]`;
+        const metaspace = this.opts!.localMetaspace;
+        const space = this.opts!.localSpace;
+
+        if (msg.type === 'auth-init') {
+            const { sAddr } = msg;
+            if (logalot) { console.log(`${lc} auth-init for ${sAddr}`); }
+
+            const authorizedS = await this.getSessionKeystone(sAddr);
+            const connectPool = (authorizedS.data?.challengePools ?? [])
+                .find(p => p.id === SESSION_KEYSTONE_POLICY.CONNECT_POOL.ID);
+            if (!connectPool) {
+                throw new Error(`Session keystone missing "${SESSION_KEYSTONE_POLICY.CONNECT_POOL.ID}" pool (E: 66b2a2e32db8f03168f6f2a8b746cb26)`);
+            }
+
+            // Demand random challenges
+            const challengeIds = Object.keys(connectPool.challenges);
+            this.demandedIds = challengeIds.sort(() => 0.5 - Math.random()).slice(0, SESSION_KEYSTONE_POLICY.CONNECT_POOL.SERVER_DEMAND_COUNT);
+
+            // Resolve secure S TJP
+            const past = authorizedS.rel8ns?.past;
+            this.sessionS_tjpAddr = (past && past.length > 0) ? past[0] : getIbGibAddr({ ibGib: authorizedS });
+
+            this.socketWrapper!.send(JSON.stringify({
+                type: 'auth-challenge',
+                challengeUuid: this.challengeUuid,
+                demandedIds: this.demandedIds
+            }));
+
+        } else if (msg.type === 'auth-proof') {
+            const { proofFrame } = msg;
+            if (logalot) { console.log(`${lc} verifying auth-proof...`); }
+
+            if (!this.sessionS_tjpAddr) {
+                throw new Error(`Missing active connect session TJP address (E: bf271853de61a04b6d05d6889263f826)`);
+            }
+
+            const sAddr_latest = await metaspace.getLatestAddr({ tjpAddr: this.sessionS_tjpAddr, space });
+            if (!sAddr_latest) {
+                throw new Error(`Authorized session keystone tip not found (E: b8cda5cdc058903318db536f59e8e826)`);
+            }
+
+            const sKeystone_latest = await this.getSessionKeystone(sAddr_latest);
+
+            // Crytographically verify proof evolution and demand solutions
+            await verifyConnectProof({
+                proofFrame,
+                sKeystone_latest,
+                challengeUuid: this.challengeUuid!,
+                demandedIds: this.demandedIds!
+            });
+
+            // Persist the newly validated evolved session keystone tip
+            await metaspace.put({ ibGibs: [proofFrame], space });
+
+            if (logalot) { console.log(`${lc} connect validation successful! Connection upgraded to active sync session.`); }
+            this.isAuthenticated = true;
+
+            this.socketWrapper!.send(JSON.stringify({
+                type: 'auth-ok'
+            }));
+        } else {
+            throw new Error(`Unexpected message type ${msg.type} during connect phase (E: f67a0f47f8426c2b01af5bc3d0146b26)`);
+        }
+    }
+
+    /**
+     * Executes the transaction turn through the local SyncSagaCoordinator.
+     */
+    public async handleIncomingSyncRequest({
+        context,
+        payloadIbGibsControl = [],
+    }: {
+        context: SyncSagaContextIbGib_V1;
+        payloadIbGibsControl?: IbGib_V1[];
+    }): Promise<SyncSagaContextIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.handleIncomingSyncRequest.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting incoming sync turn...`); }
+
+            if (!this.opts) { throw new Error(`opts not initialized. (E: 0c98186714e85b9a08bb9d98daada826)`); }
+            const { localCoordinator, localMetaspace, localSpace } = this.opts;
+            const localTempSpace = await this.ensureLocalTempSpace();
+
+            // Put control ibgibs into durable space
+            const allControlIbGibs = [context, ...payloadIbGibsControl];
+            for (const ibGib of allControlIbGibs) {
+                await putInSpace({ space: localSpace, ibGibs: [ibGib] });
+                await registerNewIbGib({ space: localSpace, ibGib });
+            }
+
+            // Authenticate context signature
+            const authErrors = await authenticateContext({
+                context,
+                space: localSpace,
+            });
+            if (authErrors.length > 0) {
+                throw new Error(`Context authentication failed: ${authErrors.join(', ')} (E: 424bd9b03ff8a42df8b1a438ed393726)`);
+            }
+
+            // Put incoming domain payloads into temp space
+            if (context.payloadIbGibsDomain && context.payloadIbGibsDomain.length > 0) {
+                for (const ibGib of context.payloadIbGibsDomain) {
+                    await putInSpace({ space: localTempSpace, ibGibs: [ibGib] });
+                }
+            }
+
+            // Evolve frame and run next coordinator sync turn
+            const responseCtx = await localCoordinator.continueSync({
+                sagaContext: context,
+                metaspace: localMetaspace,
+                mySpace: localSpace,
+                myTempSpace: localTempSpace,
+            });
+
+            return responseCtx || undefined;
+        } catch (error) {
+            console.error(`${lc} handleIncomingSyncRequest turn execution failed: ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+}