@ibgib/core-gib 0.1.48 → 0.1.50

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

@@ -0,0 +1,129 @@
+/**
+ * @module sync-peer-http-sender-v1
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { SyncPeer_V1 } from '../sync-peer-v1.mjs';
+import { SyncSagaContextIbGib_V1 } from '../../sync-saga-context/sync-saga-context-types.mjs';
+import { IbGibSpaceAny } from '../../../witness/space/space-base-v1.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+import {
+    InitializeSyncPeerHttpSenderOpts,
+    SyncPeerHttpSenderData_V1,
+    SyncPeerHttpSenderRel8ns_V1,
+    SyncPeerHttpSenderIbGib_V1
+} from './sync-peer-http-sender-types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * Http Sender Peer implementation.
+ * Sends Context to a remote server utilizing POST for uplink and SSE for downlink.
+ */
+export class SyncPeerHttpSender_V1
+    extends SyncPeer_V1<InitializeSyncPeerHttpSenderOpts>
+    implements SyncPeerHttpSenderIbGib_V1 {
+
+    protected override lc: string = `[${SyncPeerHttpSender_V1.name}]`;
+
+    override get classname(): string {
+        return SyncPeerHttpSender_V1.name;
+    }
+
+    declare data: SyncPeerHttpSenderData_V1 | undefined;
+    declare rel8ns: SyncPeerHttpSenderRel8ns_V1 | undefined;
+
+    /**
+     * Stored reference to the SSE EventSource connection.
+     * Ensure you polyfill EventSource in Node environments if needed.
+     */
+    protected eventSource?: EventSource;
+
+    constructor(
+        initialData: SyncPeerHttpSenderData_V1,
+        initialRel8ns?: SyncPeerHttpSenderRel8ns_V1,
+    ) {
+        super(initialData, initialRel8ns);
+    }
+
+
+
+    protected override async sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.sendContextRequest.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            if (!this.data?.syncEventsRoute) { throw new Error(`data.syncEventsRoute required.`); }
+            if (!this.data?.syncRoute) { throw new Error(`data.syncRoute required.`); }
+
+            // 1. Establish SSE connection to `this.data.syncEventsRoute` if not already open
+            //    (In a real implementation, you might initialize this elsewhere or ensure it stays reconnecting)
+            if (!this.eventSource) {
+                if (logalot) { console.log(`${lc} initializing EventSource to ${this.data.syncEventsRoute}`); }
+                this.eventSource = new EventSource(this.data.syncEventsRoute);
+                this.eventSource.onerror = (err) => console.error(`${lc} EventSource error:`, err);
+            }
+
+            return new Promise<SyncSagaContextIbGib_V1 | undefined>(async (resolve, reject) => {
+                // 2. Setup listeners for SSE incoming context and ibgib payloads
+                const onMessage = async (event: MessageEvent) => {
+                    try {
+                        const parsedData = JSON.parse(event.data);
+
+                        // TODO [USER]: Determine if `parsedData` is a domain payload ibGib OR the final response context.
+                        // e.g.:
+                        // if (parsedData.isDomainIbGib) {
+                        //     // Deserialize to IbGib_V1
+                        //     const ibGib = parsedData;
+                        //     await this.payloadIbGibsDomainReceived$.next(ibGib);
+                        // } else if (parsedData.isResponseContext) {
+                        //     // Deserialize to SyncSagaContextIbGib_V1
+                        //     const responseContext = parsedData;
+                        //     this.eventSource?.removeEventListener('message', onMessage);
+                        //     resolve(responseContext);
+                        // }
+                    } catch (e) {
+                        console.error(`${lc} failed to parse SSE message`, e);
+                    }
+                };
+
+                this.eventSource!.addEventListener('message', onMessage);
+
+                try {
+                    // 3. Serialize Context and Control IbGibs
+                    // TODO [USER]: Serialize the `context` and `controlIbGibs` into your wire format
+                    const payloadBody = JSON.stringify({
+                        context: context,
+                        // controlIbGibs: ...
+                    });
+
+                    // 4. POST the context to `this.data.syncRoute`
+                    if (!this.data) { throw new Error(`(UNEXPECTED) this.data falsy? (E: 8c6aa9e1aa7869465a26ee3a7d136826)`); }
+                    const response = await fetch(this.data.syncRoute, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            // Add Authorization headers here if needed
+                        },
+                        body: payloadBody,
+                    });
+
+                    if (!response.ok) {
+                        throw new Error(`HTTP Sync Error: ${response.status} ${await response.text()}`);
+                    }
+
+                    // 5. Wait for the SSE stream response to resolve with the responseContext
+                    // The Promise will remain pending until `onMessage` identifies the final response context and calls resolve().
+                } catch (e) {
+                    this.eventSource?.removeEventListener('message', onMessage);
+                    reject(e);
+                }
+            });
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/sync/sync-peer/sync-peer-http.respec.mts

@@ -0,0 +1,364 @@
+/**
+ * @module sync-peer-http.respec
+ *
+ * Verifies SyncSagaCoordinator using a mock HTTP/SSE "thin layer".
+ * This utilizes SyncPeerHttpSender_V1 and SyncPeerHttpReceiver_V1 for network synchronization simulations.
+ */
+
+import * as cp from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+import {
+    respecfully, lastOfAll, iReckon, ifWe, ifWeMight
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const maam = `[${import.meta.url}]`, sir = maam;
+import { clone, delay, extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
+import { SyncSagaCoordinator } from '../sync-saga-coordinator.mjs';
+import { getFromSpace, putInSpace, registerNewIbGib } from '../../witness/space/space-helper.mjs';
+import { Metaspace_Innerspace } from '../../witness/space/metaspace/metaspace-innerspace/metaspace-innerspace.mjs';
+import { InnerSpace_V1 } from '../../witness/space/inner-space/inner-space-v1.mjs';
+import { createTimelineRootTestHelper, getTestKeystoneServiceHelper } from '../../test-helpers.mjs';
+import { mut8Timeline, } from '../../timeline/timeline-api.mjs';
+import { DEFAULT_INNER_SPACE_DATA_V1 } from '../../witness/space/inner-space/inner-space-types.mjs';
+import { toDto } from '../../common/other/ibgib-helper.mjs';
+import { getSyncSagaFrameDependencyGraph } from '../sync-helpers.mjs';
+import { SyncIbGib_V1 } from '../sync-types.mjs';
+import { SyncPeerHttpSender_V1 } from './sync-peer-http-sender/sync-peer-http-sender-v1.mjs';
+import { SyncPeerHttpReceiver_V1 } from './sync-peer-http-receiver/sync-peer-http-receiver-v1.mjs';
+import { SyncPeerHttpSenderData_V1 } from './sync-peer-http-sender/sync-peer-http-sender-types.mjs';
+import { SyncPeerHttpReceiverData_V1 } from './sync-peer-http-receiver/sync-peer-http-receiver-types.mjs';
+import { SyncSagaContextIbGib_V1 } from '../sync-saga-context/sync-saga-context-types.mjs';
+import { SyncHttpNodeAdapter_V1 } from './sync-peer-http-receiver/sync-http-node-adapter.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+const lc = `[sync-peer-http.respec]`;
+
+await respecfully(sir, `Sync HTTP Peers`, async () => {
+
+    let metaspace: Metaspace_Innerspace;
+    let sourceSpace: InnerSpace_V1;
+    let destSpace: InnerSpace_V1;
+
+    // We focus this test initially for development
+    await ifWeMight(sir, `Basic Push Sync over Mocked HTTP/SSE`, async () => {
+        // 1. Setup Spaces
+        metaspace = new Metaspace_Innerspace(undefined);
+        await metaspace.initialize({
+            getFnAlert: () => async ({ title, msg }) => { console.log(`[Alert] ${title}: ${msg}`); },
+            getFnPrompt: () => async ({ title, msg }) => { console.log(`[Prompt] ${title}: ${msg}`); return ''; },
+            getFnPromptPassword: () => async (title, msg) => { console.log(`[PromptPwd] ${title}: ${msg}`); return null; },
+        });
+        while (!metaspace.initialized) { await delay(10); }
+
+        const defaultLocalUserSpace = await metaspace.getLocalUserSpace({ lock: false });
+        if (!defaultLocalUserSpace) { throw new Error(`(UNEXPECTED) defaultLocalUserSpace falsy?`); }
+        await defaultLocalUserSpace.initialized;
+
+        sourceSpace = new InnerSpace_V1({
+            ...DEFAULT_INNER_SPACE_DATA_V1,
+            name: 'source',
+            uuid: 'source_uuid',
+            description: 'source test space',
+        });
+        await sourceSpace.initialized;
+
+        destSpace = new InnerSpace_V1({
+            ...DEFAULT_INNER_SPACE_DATA_V1,
+            name: 'dest',
+            uuid: 'dest_uuid',
+            description: 'dest test space',
+        });
+        await destSpace.initialized;
+
+        // 2. Seed Source Data
+        if (logalot) { console.log(`${lc} Creating data in Source...`); }
+        const root = await createTimelineRootTestHelper({
+            ib: 'timeline_root',
+            data: { type: 'root', },
+            space: sourceSpace,
+        });
+
+        const child = await mut8Timeline({
+            timeline: root,
+            mut8Opts: {
+                dataToAddOrPatch: { type: 'child', },
+            },
+            metaspace,
+            space: sourceSpace,
+        });
+        const childAddr = getIbGibAddr({ ibGib: child });
+
+        // 3. Setup Coordinators & Peer
+        if (logalot) { console.log(`${lc} Setting up Coordinators...`); }
+        const mockKeystone = await getTestKeystoneServiceHelper();
+
+        const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
+        const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
+
+        // --- Mocking the HTTP "Network" ---
+        // Instead of real fetch and EventSource, we wire the Sender's outgoing HTTP
+        // calls directly to the Receiver's incoming endpoints.
+
+        const receiverPeerData: SyncPeerHttpReceiverData_V1 = { classname: SyncPeerHttpReceiver_V1.name };
+        const receiverPeer = new SyncPeerHttpReceiver_V1(receiverPeerData);
+        await receiverPeer.initialized;
+        await receiverPeer.initializeOpts({
+            localCoordinator: receiverCoordinator,
+            localMetaspace: metaspace,
+            localSpace: destSpace,
+        });
+
+        // We'll subclass/monkey-patch the Sender peer to use mock fetching
+        class MockSyncPeerHttpSender extends SyncPeerHttpSender_V1 {
+            override async sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
+                // Mock POST /sync/frame
+                // Real sender would serialize and POST. Here we just hand it to receiver:
+                const responsePromise = new Promise<SyncSagaContextIbGib_V1 | undefined>(async (resolve, reject) => {
+                    try {
+                        const rel8ns = context.rel8ns;
+                        if (!rel8ns || (rel8ns.sagaFrame || []).length !== 1) { throw new Error(`(UNEXPECTED) context.rel8ns.sagaFrame missing?`); }
+                        const sagaAddr = rel8ns.sagaFrame![0];
+                        const getSagaRes = await getFromSpace({ addr: sagaAddr, space: sourceSpace });
+                        const sagaFrame = getSagaRes.ibGibs![0] as SyncIbGib_V1;
+
+                        const { msgStones, identities } = await getSyncSagaFrameDependencyGraph({
+                            sagaIbGib: sagaFrame,
+                            localSpace: sourceSpace,
+                        });
+                        const msg = msgStones[0];
+                        const controlIbGibs = [...identities, msg, sagaFrame, context].filter(x => !!x).map(x => toDto({ ibGib: x }));
+
+                        // The Server Adapter calls receiverPeer.handleIncomingSyncRequest
+                        const responseContext = await receiverPeer.handleIncomingSyncRequest({
+                            context,
+                            controlIbGibs
+                        });
+
+                        if (!responseContext) {
+                            resolve(undefined);
+                            return;
+                        }
+
+                        // **Mock the Server Adapter returning data**
+                        // Real server would stream the newly evolved Control Context ibgibs to SSE,
+                        // followed by the response domain payload ibgibs.
+                        // We must MANUALLY persist the control ibgibs to the sender space FIRST,
+                        // to simulate the client downloading and validating them from the SSE connection.
+                        await delay(100);
+                        const responseSagaAddr = responseContext.rel8ns!.sagaFrame![0];
+                        const getResponseSagaRes = await getFromSpace({ addr: responseSagaAddr, space: destSpace });
+                        const responseSagaFrame = getResponseSagaRes.ibGibs![0] as SyncIbGib_V1;
+                        const depGraphResponse = await getSyncSagaFrameDependencyGraph({
+                            sagaIbGib: responseSagaFrame,
+                            localSpace: destSpace,
+                        });
+                        const responseControlIbGibs = [
+                            ...identities, // ORIGINAL identities, not the receiver's!
+                            depGraphResponse.msgStones[0],
+                            responseSagaFrame,
+                            context
+                        ].filter(x => !!x).map(x => toDto({ ibGib: x }));
+
+                        for (const ibGib of responseControlIbGibs) {
+                            await putInSpace({ space: sourceSpace, ibGibs: [ibGib] });
+                            await registerNewIbGib({ ibGib, space: sourceSpace, fnBroadcast: undefined });
+                        }
+
+                        await delay(5); // Simulate end of SSE task event
+                        // Resolve with the responseContext
+                        resolve(responseContext);
+
+                        // THEN simulate streaming the domain payload ibgibs to the local subject
+                        if (responseContext.payloadIbGibsDomain) {
+                            new Promise<void>(async (resDom) => {
+                                for (const domainIbGib of responseContext.payloadIbGibsDomain!) {
+                                    await delay(1); // emulate network gap between SSE events
+                                    await this.payloadIbGibsDomainReceived$.next(domainIbGib);
+                                }
+                                resDom();
+                            });
+                        }
+
+                    } catch (e) {
+                        reject(e);
+                    }
+                });
+                return responsePromise;
+            }
+        }
+
+        const senderPeerData: SyncPeerHttpSenderData_V1 = {
+            classname: SyncPeerHttpSender_V1.name,
+            syncRoute: 'http://mock/sync/frame',
+            syncEventsRoute: 'http://mock/sync/events'
+        };
+        const senderPeer = new MockSyncPeerHttpSender(senderPeerData);
+        await senderPeer.initialized;
+
+        // We configure localSpace and a senderTempSpace for the mock:
+        const senderTempSpace = new InnerSpace_V1({
+            ...DEFAULT_INNER_SPACE_DATA_V1, name: 'sender_temp', uuid: 'sender_temp_uuid'
+        });
+        await senderTempSpace.initialized;
+
+        await senderPeer.initializeOpts({
+            localSpace: sourceSpace,
+            localTempSpace: senderTempSpace
+        });
+
+        // 4. Run Sync
+        if (logalot) { console.log(`${lc} Running Sync...`); }
+        try {
+            const resSync = await senderCoordinator.sync({
+                peer: senderPeer,
+                localSpace: sourceSpace,
+                metaspace: metaspace,
+                domainIbGibs: [child], // Sync the child
+                useSessionIdentity: false, // Testing logic only
+            });
+
+            await resSync.done;
+            iReckon(sir, true).asTo('Mocked request ran').isGonnaBeTrue();
+
+            // We now expect the entire saga to complete because handleIncomingSyncRequest works
+            let childInDest = await getFromSpace({ addr: childAddr, space: destSpace });
+            iReckon(sir, childInDest.success).asTo('Child is correctly pushed to destination space').isGonnaBeTrue();
+
+        } catch (error: any) {
+            console.error(`${lc}[senderCoordinator.sync] FULL ERROR:`, error.stack || error.message || error);
+            // Will fail initially because handleIncomingSyncRequest is not implemented
+            iReckon(sir, false).asTo(`Unexpected error: ${extractErrorMsg(error)}`).isGonnaBeTrue();
+        }
+
+    });
+
+    await respecfully(sir, `Real Sync via Local HTTP/2 Node Adapter with Self-Signed Certs`, async () => {
+        // 1. Generate Self-Signed Certs via OpenSSL or PowerShell
+        const tmpDir = path.join(process.cwd(), 'tmp-certs');
+        const keyPath = path.join(tmpDir, 'server.key');
+        const certPath = path.join(tmpDir, 'server.cert');
+        const pfxPath = path.join(tmpDir, 'server.pfx');
+
+        let hasTlsGenerator = false;
+        let isWin = process.platform === 'win32';
+
+        if (isWin) {
+            hasTlsGenerator = true;
+        } else {
+            try {
+                cp.execSync('openssl version', { stdio: 'ignore' });
+                hasTlsGenerator = true;
+            } catch (e) {
+                console.warn(`${lc} OpenSSL not found in PATH. Skipping HTTP/2 Native test.`);
+            }
+        }
+
+        if (hasTlsGenerator) {
+            if (!fs.existsSync(tmpDir)) { fs.mkdirSync(tmpDir, { recursive: true }); }
+
+            let keyInfo: Buffer | undefined;
+            let certInfo: Buffer | undefined;
+            let pfxInfo: Buffer | undefined;
+
+            if (isWin) {
+                if (!fs.existsSync(pfxPath)) {
+                    if (logalot) { console.log(`${lc} Generating self-signed cert via PowerShell...`); }
+                    const psScript = `
+                        $cert = New-SelfSignedCertificate -CertStoreLocation "Cert:\\CurrentUser\\My" -Subject "localhost" -KeyExportPolicy Exportable -NotAfter (Get-Date).AddDays(1)
+                        $pwd = ConvertTo-SecureString -String "testpass" -Force -AsPlainText
+                        Export-PfxCertificate -Cert $cert -FilePath "${pfxPath.replace(/\\/g, '\\\\')}" -Password $pwd
+                        Remove-Item -Path $cert.PSPath
+                    `;
+                    cp.execSync(`powershell -Command "${psScript.replace(/\n/g, '; ')}"`, { stdio: 'ignore' });
+                }
+                pfxInfo = fs.readFileSync(pfxPath);
+            } else {
+                if (!fs.existsSync(keyPath) || !fs.existsSync(certPath)) {
+                    if (logalot) { console.log(`${lc} Generating self-signed cert...`); }
+                    cp.execSync(`openssl req -x509 -newkey rsa:2048 -nodes -keyout ${keyPath} -out ${certPath} -days 1 -subj "/CN=localhost"`, { stdio: 'ignore' });
+                }
+                keyInfo = fs.readFileSync(keyPath);
+                certInfo = fs.readFileSync(certPath);
+            }
+
+            // Bypass self-signed cert rejection in Node fetch
+            process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+
+            // 2. Setup Spaces
+            metaspace = new Metaspace_Innerspace(undefined);
+            await metaspace.initialize({
+                getFnAlert: () => async () => { },
+                getFnPrompt: () => async () => '',
+                getFnPromptPassword: () => async () => null,
+            });
+            while (!metaspace.initialized) { await delay(10); }
+
+            const defaultLocalUserSpace = await metaspace.getLocalUserSpace({ lock: false });
+            await defaultLocalUserSpace?.initialized;
+
+            sourceSpace = new InnerSpace_V1({ ...DEFAULT_INNER_SPACE_DATA_V1, name: 'source_h2', uuid: 'source_h2_uuid' });
+            await sourceSpace.initialized;
+            destSpace = new InnerSpace_V1({ ...DEFAULT_INNER_SPACE_DATA_V1, name: 'dest_h2', uuid: 'dest_h2_uuid' });
+            await destSpace.initialized;
+
+            // 3. Setup Node Adapter & Receiver
+            const mockKeystone = await getTestKeystoneServiceHelper();
+            const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
+
+            const receiverPeer = new SyncPeerHttpReceiver_V1({ classname: SyncPeerHttpReceiver_V1.name });
+            await receiverPeer.initialized;
+            await receiverPeer.initializeOpts({
+                localCoordinator: receiverCoordinator,
+                localMetaspace: metaspace,
+                localSpace: destSpace,
+            });
+
+            const port = 8443;
+            const adapter = new SyncHttpNodeAdapter_V1({
+                receiverPeer,
+                port,
+                key: keyInfo,
+                cert: certInfo,
+                pfx: pfxInfo,
+                passphrase: 'testpass',
+                basePath: '/sync'
+            });
+
+            await adapter.start();
+
+            // 4. Test the Adapter Connection
+            if (logalot) { console.log(`${lc} Pinging the HTTP/2 Adapter via POST...`); }
+
+            // Create a dummy context structure just to appease the parser and prove connection success
+            const testContext: any = { classname: 'SyncSagaContextIbGib_V1', rel8ns: {}, data: {} };
+            const payloadBody = JSON.stringify({ context: testContext, controlIbGibs: [] });
+
+            try {
+                const res = await fetch(`https://localhost:${port}/sync/frame`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', 'x-client-id': 'test-123' },
+                    body: payloadBody
+                });
+
+                await ifWeMight(sir, 'check http2 adapter', async () => {
+                    iReckon(sir, res.ok).asTo('Successfully reached HTTP/2 Adapter via POST').isGonnaBeTrue();
+                });
+
+
+                // The receiver peer inside the adapter will throw a normal logged warning about invalid saga formats from our dummy context,
+                // but the HTTP transport should respond 200 OK, verifying the http2 server is cleanly bound!
+
+            } catch (err) {
+                console.error(`${lc} HTTP/2 test failed:`, err);
+                iReckon(sir, false).asTo('HTTP/2 Adapter POST should not throw').isGonnaBeTrue();
+            } finally {
+                await adapter.stop();
+            }
+        }
+    });
+
+});

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

@@ -15,30 +15,30 @@ import { SyncPeerData_V1, SyncPeerRel8ns_V1 } from '../sync-peer-types.mjs';
  */
 export interface SyncPeerInnerspaceOptions {
     /**
-     * The "receiver" durable space (not temp). 
-     * 
+     * The "receiver" durable space (not temp).
+     *
      * ## notes
-     * 
+     *
      * when syncing/merging locally, we are working with two spaces and this
      * acts as the "remote" space even though it's technically still local.
      */
     receiverSpace: IbGibSpaceAny;
     /**
-     * Coordinator for the "receiver". 
-     * 
+     * Coordinator for the "receiver".
+     *
      * @see {@link receiverSpace} notes.
      */
     receiverCoordinator: SyncSagaCoordinator;
     /**
-     * Metaspace for the "receiver". 
-     * 
+     * Metaspace for the "receiver".
+     *
      * @see {@link receiverSpace} notes.
      */
     receiverMetaspace: MetaspaceService;
     /**
      * Temporary sync transaction space for the "receiver", for storage of
      * domain ibgibs created/received throughout the sync saga until commit.
-     * 
+     *
      * @see {@link receiverSpace} notes.
      */
     receiverTempSpace: IbGibSpaceAny;

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

@@ -67,7 +67,7 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<InitializeSyncPeerInnersp
         super(initialData, initialRel8ns);
     }
 
-    protected override async ensureReceiverTempSpace(): Promise<IbGibSpaceAny> {
+    protected async ensureReceiverTempSpace(): Promise<IbGibSpaceAny> {
         const lc = `${this.lc}[${this.ensureReceiverTempSpace.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting... (I: bab87f15dea77cd4892bd8a8d2e65826)`); }
@@ -108,14 +108,17 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<InitializeSyncPeerInnersp
 
             if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: d8b1348e3233810128999596b1fa5826)`); }
 
+            await this.ensureReceiverTempSpace();
+
             const {
-                senderSpace, senderTempSpace,
+                localSpace, localTempSpace,
                 receiverSpace, receiverCoordinator, receiverMetaspace,
                 receiverTempSpace
             } = this.opts;
 
             if (logalot) { console.log(`${lc} starting...Context: ${getIbGibAddr({ ibGib: context })}`); }
 
+
             const { sagaFrame } = context;
 
             // The context has already been validated, authenticated and authorized at this point.
@@ -128,7 +131,7 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<InitializeSyncPeerInnersp
             if (!sagaFrame.data) { throw new Error(`(UNEXPECTED) sagaFrame.data falsy? (E: f30e290a8b770e1b387377420ea73a26)`); }
             if (!sagaFrame.rel8ns) { throw new Error(`(UNEXPECTED) sagaFrame.rel8ns falsy? (E: f888caa698b8cf6b4893b7fd6df09726)`); }
             if (!receiverTempSpace) { throw new Error(`(UNEXPECTED) receiverTempSpace falsy? (E: 3b46d838f6fc645c58b29215bfddb826)`); }
-            if (!senderTempSpace) { throw new Error(`(UNEXPECTED) senderTempSpace falsy? (E: b187a8f913c2295ae90d7ae2b47b6a26)`); }
+            if (!localTempSpace) { throw new Error(`(UNEXPECTED) localTempSpace falsy? (E: b187a8f913c2295ae90d7ae2b47b6a26)`); }
             // #endregion sanity validation assertions
 
             // let localSpace: IbGibSpaceAny;
@@ -149,7 +152,7 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<InitializeSyncPeerInnersp
 
             const { sagaIbGib: _alreadyHave, msgStones, identities } = await getSyncSagaFrameDependencyGraph({
                 sagaIbGib: sagaFrame,
-                localSpace: senderSpace,
+                localSpace: localSpace,
             });
             if (msgStones.length !== 1) { throw new Error(`(UNEXPECTED) msgStones.length !== 1? we're only geared for a single msg stone that is always present (not 0, not greater than 1) (E: 2d3138ed130f1aca116551889483e826)`); }
             const msg = msgStones[0];
@@ -238,13 +241,13 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<InitializeSyncPeerInnersp
             // ...put into sender's durable space
             await putInSpace({
                 ibGibs: responsePayloadIbGibsControl,
-                space: senderSpace,
+                space: localSpace,
             });
             // register yet??
             for (const control of responsePayloadIbGibsControl) {
                 await registerNewIbGib({
                     ibGib: control,
-                    space: senderSpace,
+                    space: localSpace,
                     fnBroadcast: undefined
                 });
             }
@@ -266,7 +269,7 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<InitializeSyncPeerInnersp
 
                         await putInSpace_dnasThenNonDnas({
                             ibGibs: payloadIbGibsDomain_response,
-                            space: senderTempSpace,
+                            space: localTempSpace,
                         });
 
                         for (const payloadDomain of payloadIbGibsDomain_response) {

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

@@ -35,20 +35,20 @@ export interface SyncPeerIbGib_V1 extends IbGib_V1<SyncPeerData_V1, SyncPeerRel8
  */
 export interface InitializeSyncPeerOpts {
     /**
-     * sender's durable space.
-     * 
+     * local durable space.
+     *
      * will store control ibgibs (context, sync saga ibgib, control msg stones)
-     * here (and in {@link senderTempSpace}) throughout the process for audit trail.
+     * here (and in {@link localTempSpace}) throughout the process for audit trail.
      */
-    senderSpace: IbGibSpaceAny;
+    localSpace: IbGibSpaceAny;
     /**
-     * sender's temporary space for the entire sync transaction.
-     * 
+     * local temporary space for the entire sync transaction.
+     *
      * In addition to control ibgibs which are stored in both temp and durable
      * spaces, this temp space will be where domain ibgibs are stored that are
      * received/created throughout the transaction until commit.
      */
-    senderTempSpace?: IbGibSpaceAny;
+    localTempSpace?: IbGibSpaceAny;
 }
 
 /**
@@ -69,9 +69,9 @@ export interface SyncPeerWitness<TInitializeOpts extends InitializeSyncPeerOpts
 
     /**
      * sender-specific opts/config
-     * 
+     *
      * ## notes
-     * 
+     *
      * I'm doing this hack because I have to be able to create a peer without
      * being able to fully configure it at construction time. So I can't place
      * this init code in the {@link initialize} method.
@@ -81,14 +81,14 @@ export interface SyncPeerWitness<TInitializeOpts extends InitializeSyncPeerOpts
     /**
      * use this to set the senderTempSpace and any other optional opts that need
      * to be configured just before sending any contexts across the wire.
-     * 
+     *
      * @see {@link opts}
      */
     setOptionalOpts(arg: Partial<TInitializeOpts>): void;
 
     /**
      * Observable for streaming large domain payloads asynchronously.
-     * 
+     *
      * Implementations should publish domain ibgibs to this observable as they are received.
      * The handling code (e.g. SyncSagaCoordinator) will subscribe to this.
      */