@ibgib/core-gib 0.1.23 → 0.1.25

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

@@ -1,17 +1,7 @@
 /**
- * @module SyncPeer_V1 witness class
- * 
- * 
- * NOTE: All push/pulls in this were done to get to compile. These should mostly
- * not be single push/pull calls but should be batched with multiple addresses
- * NOTE: All push/pulls in this were done to get to compile. These should mostly
- * not be single push/pull calls but should be batched with multiple addresses
- * NOTE: All push/pulls in this were done to get to compile. These should mostly
- * not be single push/pull calls but should be batched with multiple addresses
- * NOTE: All push/pulls in this were done to get to compile. These should mostly
- * not be single push/pull calls but should be batched with multiple addresses
- * NOTE: All push/pulls in this were done to get to compile. These should mostly
- * not be single push/pull calls but should be batched with multiple addresses
+ * @module SyncPeer_V1 witness class for base class plumbing of sync peers.
+ *
+ * You are expected to implement concrete peer classes for concrete architecture.
  */
 
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
@@ -24,11 +14,11 @@ import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
 import { SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from '../sync-constants.mjs';
 import { SubjectWitness } from '../../common/pubsub/subject/subject-types.mjs';
 import { SyncSagaContextIbGib_V1 } from '../sync-saga-context/sync-saga-context-types.mjs';
-import { SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWitness } from './sync-peer-types.mjs';
+import { InitializeSyncPeerOpts, SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWitness } from './sync-peer-types.mjs';
 import { LightWitnessBase_V1 } from '../../witness/light-witness-base-v1.mjs';
 import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
 import { newupSubject } from '../../common/pubsub/subject/subject-helper.mjs';
-import { validateContext } from '../sync-saga-context/sync-saga-context-helpers.mjs';
+import { validateContextAndSagaFrame } from '../sync-saga-context/sync-saga-context-helpers.mjs';
 import { getFromSpace } from '../../witness/space/space-helper.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT || true;
@@ -37,21 +27,21 @@ const lcControlDomain = '[ControlDomain]';
 
 /**
  * Abstract witness for talking to a Sync Peer (e.g. Remote Node or Local Simulator).
- * 
+ *
  * Takes a SyncSagaContext (Request) and returns a SyncSagaContext (Response).
- * 
+ *
  * Implements the core "Sync Protocol Transport" logic:
  * 1. Push Context & Dependencies (Sender -> Receiver)
  * 2. Send Request (RPC)
  * 3. Pull Response & Dependencies (Receiver -> Sender)
  */
-export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, SyncPeerRel8ns_V1>
-    implements SyncPeerWitness {
+export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts = InitializeSyncPeerOpts>
+    extends LightWitnessBase_V1<SyncPeerData_V1, SyncPeerRel8ns_V1>
+    implements SyncPeerWitness<TInitializeOpts> {
 
     protected lc: string = `[${SyncPeer_V1.name}]`;
 
-    public senderSpace: IbGibSpaceAny;
-    public senderTempSpace: IbGibSpaceAny;
+    public opts: TInitializeOpts | undefined;
     public payloadIbGibsDomainReceived$!: SubjectWitness<IbGib_V1>;
 
     get classname(): string {
@@ -60,24 +50,79 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
         return this.data.classname;
     }
 
-    constructor(senderSpace: IbGibSpaceAny, senderTempSpace: IbGibSpaceAny, initialData: SyncPeerData_V1, initialRel8ns?: SyncPeerRel8ns_V1) {
+    constructor(initialData: SyncPeerData_V1, initialRel8ns?: SyncPeerRel8ns_V1) {
         super(initialData, initialRel8ns);
-        this.senderSpace = senderSpace;
-        this.senderTempSpace = senderTempSpace;
     }
 
-    async initialize(): Promise<void> {
+    public async initialize(): Promise<void> {
         this.payloadIbGibsDomainReceived$ = await newupSubject<IbGib_V1>();
     }
 
+    /**
+     * base implementation just sets the opts property.
+     *
+     * override this in concrete classes for further initialization code
+     * specific to the sender.
+     *
+     * @see {@link SyncPeerWitness.opts}
+     */
+    public async initializeSender(opts: TInitializeOpts): Promise<void> {
+        const lc = `${this.lc}[${this.initializeSender.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 31bd5fda37c89fa37fbaf14daf5fe726)`); }
+            this.opts = opts;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    public setOptionalOpts(arg: Partial<TInitializeOpts>): void {
+        const lc = `${this.lc}[${this.setOptionalOpts.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: ae5ddbd3577db267f84743175a736626)`); }
+            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: 0dd4d6080a6e2f31d86cf4d86e11b826)`); }
+
+            if (logalot) { console.log(`${lc} updating opts. arg keys: ${Object.keys(arg)} (I: 452d78a558f8fc3468c8e2e68c70b226)`); }
+
+            this.opts = { ...this.opts, ...arg };
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    // public setOptionalOpts({
+    //     senderTempSpace,
+    // }: {
+    //     senderTempSpace: IbGibSpaceAny,
+    // }): void {
+    //     const lc = `${this.lc}[${this.setOptionalOpts.name}]`;
+    //     try {
+    //         if (logalot) { console.log(`${lc} starting... (I: a17188953e38f07b1884e498ac490b26)`); }
+    //         if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: bdf00fe4b89b07ea78860d6ebe922e26)`); }
+
+    //         this.opts.senderTempSpace = senderTempSpace;
+    //     } catch (error) {
+    //         console.error(`${lc} ${extractErrorMsg(error)}`);
+    //         throw error;
+    //     } finally {
+    //         if (logalot) { console.log(`${lc} complete.`); }
+    //     }
+    // }
+
     protected abstract ensureReceiverTempSpace(): Promise<IbGibSpaceAny>;
 
     /**
      * Witness the synchronization context (Send/Receive).
-     * 
+     *
      * At this point in code, we are sending the context OUTGOING. The {@link context} should
      * have a fully populated {@link SyncSagaContextIbGib_V1.sagaFrame}
-     * 
+     *
      * @param arg The OUTGOING context (Request).
      * @returns The INCOMING context (Response), or undefined if failed/empty.
      */
@@ -86,27 +131,34 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
         try {
             if (logalot) { console.log(`${lc} starting...`); }
 
-            if (logalot) { console.log(`${lc} starting...`); }
-
-            // validate, authenticate, and authorize the context, sagaFrame, and identity(s)
-            const validationErrors = await validateContext({ context });
-            if (validationErrors.length > 0) {
-                throw new Error(`invalid context received. validationErrors: ${validationErrors} (E: 8b34c875c968af29bc433138e57a7826)`);
-            }
-            const authenticationErrors = await this.authenticateContext({ context });
-            if (authenticationErrors.length > 0) {
-                throw new Error(`invalid context authentication. authenticationErrors: ${authenticationErrors} (E: da89da5ee1269aeb78952d475d607526)`);
-            }
-            const authorizationErrors = await this.authorizeContext({ context });
-            if (authorizationErrors.length > 0) {
-                throw new Error(`invalid context authorization. authorizationErrors: ${authorizationErrors} (E: 8ddc284a758cf10ba829334c1babb826)`);
-            }
-
-            // at this point, we have a valid, authenticated, authorized context
+            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? Concrete class should have initialized sender opts by now. (E: 0b9e28287318fdf8bf9f5a6886a24826)`); }
+
+            // NOTE: There are two basic types of peers:
+            // * local-only (peer)
+            //   * this peer is both sender/receiver peer
+            //   * for local merges and relatively fast spaces
+            // * proxy to remote space
+            //   * this peer is both sender/receiver peer
+            //   * works directly with remote/outerspaces
+            //   * Less efficient over-the-wire xfer due to chatiness
+            // * symmetric node sender/receiver peers
+            //   * separate sender/receiver classes
+            //     * e.g., SyncPeerClient[Substrate]Sender_V1,
+            //       SyncPeerClient[Substrate]Receiver_V1
+            //   * More efficient over-the-wire xfer
+            //   * Most difficult to mentally model
+            //   * sender.witness does the pushing out
+            //     * what the sender/initiator's coordinator has a reference to
+            //   * receiver.witness does the coming in
+            //     * lives on a server/remote instance with its own coordinator
+            //       instance
+            //     * must do its own validation/authn/authz for possible MITM
+            //       issues
+            // The following is a sketch where some of these may be blurred
 
             // persist the context, sagaframe, identity(s) ONLY in the receiver's durable space
             // if sending domain ibgibs...
-            //   verify the domain ibgibs intrinsically. 
+            //   verify the domain ibgibs intrinsically.
             //   persist the domain ibgibs in the receiver's temp space (push all addrs?)
             //   await until all domain ibgibs are in receiver's temp space
             // process the context with the receiver's coordinator to get a new response context
@@ -114,15 +166,28 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
             //   validate context intrinsically
             //   validate return identity if present
             // persist the response context's dependency graph (context, saga frame and msg(s), identities)
-            // if response has payload domain ibgibs, 
+            // if response has payload domain ibgibs,
             //   spin off...
             //     pull domain ibgibs to local temp space
             //     publish domain ibgibs to observable
             //     when all domain ibgibs are pulled, publish complete to the observable
             // return resulting context ibgib (which the caller should get BEFORE the domain ibgibs observable completes)
 
-            // 1. PUSH: Ensure Request Data is available on Receiver
-            await this.pushContextGraph({ context }); // ???
+            // validate, authenticate, and authorize the context, sagaFrame, and identity(s)
+            const validationErrors = await validateContextAndSagaFrame({ context });
+            if (validationErrors.length > 0) {
+                throw new Error(`invalid context received. validationErrors: ${validationErrors} (E: 8b34c875c968af29bc433138e57a7826)`);
+            }
+            const authenticationErrors = await this.authenticateContext({ context });
+            if (authenticationErrors.length > 0) {
+                throw new Error(`invalid context authentication. authenticationErrors: ${authenticationErrors} (E: da89da5ee1269aeb78952d475d607526)`);
+            }
+            const authorizationErrors = await this.authorizeContext({ context });
+            if (authorizationErrors.length > 0) {
+                throw new Error(`invalid context authorization. authorizationErrors: ${authorizationErrors} (E: 8ddc284a758cf10ba829334c1babb826)`);
+            }
+
+            // at this point, we have a valid, authenticated, authorized context
 
             // 2. EXECUTE: Trigger Remote Processing
             const response = await this.sendContextRequest(context);
@@ -132,14 +197,12 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
                 return undefined;
             }
 
-            // at this point, we have received the response context, sync saga
-            // frame/msg stones, and any keystones should be evolved. Depending
+            // at this point, all outgoing payload domain ibgibs have been sent.
+            // we have received the response context, wherein the sync saga
+            // frame/msg stone(s) and any keystones should be evolved. Depending
             // on the concrete implementation, if there are domain ibgibs to
-            // receive, they may already be coming. 
-
-            // todo: this pull is a 
-            // 3. PULL: Ensure Response Data is available on Sender (Local)
-            await this.pullContextGraph({ context: response });
+            // receive, they may still be transferring. These will be published
+            // to this.payloadIbGibsDomainReceived$
 
             return response;
 
@@ -152,13 +215,25 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
     }
 
     /**
-     * Transmits the Context IbGib itself to the Peer.
+     * This is responsible for:
+     *
+     * * sending outgoing {@link context}, the sync saga frame and msg stone(s),
+     *   and identities...
+     * * AND sending OUTGOING domain ibgibs
+     *   {@link SyncSagaContextIbGib_V1.payloadIbGibsDomain}
+     * * getting back the other end's resultant context ibgib, sync saga frame
+     *   and msg stone(s), and identities in their entirety...
+     * * AND stream/receiving the RESPONSE payload domain ibgibs, publishing
+     *   these to this.payloadIbGibsDomainReceived$.
+     *
+     * So this returns the RESPONSE context, possibly BEFORE the RESPONSE domain
+     * ibgibs have been completely received/streamed. The coordinator is responsible
      */
     protected abstract sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined>;
 
     /**
      * Pushes specific IbGib(s) (by address) from Local to Remote.
-     * 
+     *
      * Should NOT have to handle identifying if the remote already has it
      * (optimization), because the sync coordinator should be doing this in
      * its diffing algorithm.
@@ -210,146 +285,10 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
         }
     }
 
-    /**
-     * Helper to orchestrate the PUSH of a Context's dependency graph.
-     */
-    protected async pushContextGraph({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<void> {
-        const lc = `[${SyncPeer_V1.name}][pushContextGraph]`;
-
-        // A. Push Context Envelope
-        const contextAddr = getIbGibAddr({ ibGib: context });
-        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH Context Envelope -> ${contextAddr} (I: 3f4e5a6b7c8d9e0f)`); }
-        await this.push([contextAddr]);
-
-        // B. Push Saga Frame & Immediate Deps (Msg, Identity)
-        const frameAddr = context.rel8ns?.sagaFrame?.[0];
-        if (frameAddr) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Saga Frame -> ${frameAddr} (I: 4a5b6c7d8e9f0a1b)`); }
-            await this.push([frameAddr]);
-            // We inspect the local frame to find its immediate deps
-            const frame = await this.getLocalIbGib(frameAddr);
-            if (frame) {
-                // Msg Stone
-                const msgAddrs = frame.rel8ns?.[SYNC_MSG_REL8N_NAME];
-                if (msgAddrs) {
-                    for (const addr of msgAddrs) {
-                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Msg Stone -> ${addr} (I: 5b6c7d8e9f0a1b2c)`); }
-                        await this.push([addr]);
-                    }
-                }
-                // Identity
-                const idAddrs = frame.rel8ns?.identity;
-                if (idAddrs) {
-                    for (const addr of idAddrs) {
-                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Identity -> ${addr} (I: 6c7d8e9f0a1b2c3d)`); }
-                        await this.push([addr]);
-                    }
-                }
-            }
-        }
-
-        // C. Push Session Identity
-        const sessionKeystoneAddr = context.rel8ns?.sessionKeystone?.[0];
-        if (sessionKeystoneAddr) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Session Keystone -> ${sessionKeystoneAddr} (I: 7d8e9f0a1b2c3d4e)`); }
-            await this.push([sessionKeystoneAddr]);
-        }
-
-        // D. Push Payloads (Deep/Soft)
-        // For payloads, the Peer is just a transport. It doesn't know the structure.
-        // It relies on "push" handling the "deep" transfer if needed, or we explicitly iterate if we had a graph.
-        // But since we are "Witnessing", we usually assume "push(addr)" acts like "copy(addr, recursive=true)"?
-        // Or do we need to be explicit?
-        // User said: "payloads should be flat... sync coordinator is the one doing the heavy lifting".
-        // So we just push the addrs listed.
-
-        // 1. Control Payloads
-        // const controlAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_CONTROL];
-        // if (controlAddrs && controlAddrs.length > 0) {
-        //     if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL PAYLOADS (${controlAddrs.length}): ${controlAddrs.join(', ')} (I: 8e9f0a1b2c3d4e5f)`); }
-        //     for (const addr of controlAddrs) {
-        //         await this.push(addr);
-        //     }
-        // }
-
-        // 2. Domain Payloads
-        const domainAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN];
-        if (domainAddrs && domainAddrs.length > 0) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH DOMAIN PAYLOADS (${domainAddrs.length}): ${domainAddrs.join(', ')} (I: 9f0a1b2c3d4e5f6a)`); }
-            for (const addr of domainAddrs) {
-                await this.push([addr]);
-            }
-        }
-
-        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH COMPLETE for context ${contextAddr} (I: a0b1c2d3e4f5a6b7)`); }
-    }
-
-    /**
-     * Helper to orchestrate the PULL of a Context's dependency graph.
-     */
-    protected async pullContextGraph({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<void> {
-        const lc = `[${SyncPeer_V1.name}][pullContextGraph]`;
-
-        // A. Pull Context Envelope
-        const contextAddr = getIbGibAddr({ ibGib: context });
-        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL Context Envelope <- ${contextAddr} (I: b1c2d3e4f5a6b7c8)`); }
-        await this.pull([contextAddr]);
-
-        // B. Pull Saga Frame & Immediate Deps
-        const frameAddr = context.rel8ns?.sagaFrame?.[0];
-        if (frameAddr) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Saga Frame <- ${frameAddr} (I: c2d3e4f5a6b7c8d9)`); }
-            await this.pull([frameAddr]);
-            // Inspect REMOTE frame? We need to have pulled it first.
-            const frame = await this.getLocalIbGib(frameAddr); // Should be local now
-            if (frame) {
-                const msgAddrs = frame.rel8ns?.[SYNC_MSG_REL8N_NAME];
-                if (msgAddrs) {
-                    for (const addr of msgAddrs) {
-                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Msg Stone <- ${addr} (I: d3e4f5a6b7c8d9e0)`); }
-                        await this.pull([addr]);
-                    }
-                }
-                const idAddrs = frame.rel8ns?.identity;
-                if (idAddrs) {
-                    for (const addr of idAddrs) {
-                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Identity <- ${addr} (I: e4f5a6b7c8d9e0f1)`); }
-                        await this.pull([addr]);
-                    }
-                }
-            }
-        }
-
-        // C. Pull Session Identity
-        const sessionKeystoneAddr = context.rel8ns?.sessionKeystone?.[0];
-        if (sessionKeystoneAddr) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Session Keystone <- ${sessionKeystoneAddr} (I: f5a6b7c8d9e0f1a2)`); }
-            await this.pull([sessionKeystoneAddr]);
-        }
-
-        // D. Pull Payloads
-        // const controlAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_CONTROL];
-        // if (controlAddrs && controlAddrs.length > 0) {
-        //     if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL PAYLOADS (${controlAddrs.length}): ${controlAddrs.join(', ')} (I: a6b7c8d9e0f1a2b3)`); }
-        //     for (const addr of controlAddrs) {
-        //         await this.pull(addr);
-        //     }
-        // }
-        const domainAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN];
-        if (domainAddrs && domainAddrs.length > 0) {
-            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL DOMAIN PAYLOADS (${domainAddrs.length}): ${domainAddrs.join(', ')} (I: b7c8d9e0f1a2b3c4)`); }
-            for (const addr of domainAddrs) {
-                await this.pull([addr]);
-            }
-        }
-
-        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL COMPLETE for context ${contextAddr} (I: c8d9e0f1a2b3c4d5)`); }
-    }
-
     /**
      * Abstract accessor to get an IbGib from the Local space/store.
      * Needed for inspecting rela8ns during the graph walk.
-     * 
+     *
      * Default implementation simply looks in senderSpace
      */
     protected async getLocalIbGib(addr: string): Promise<IbGib_V1 | undefined> {
@@ -358,14 +297,15 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
             if (logalot) { console.log(`${lc} starting... (I: 27b248cb9801eeb2386b71485389a826)`); }
 
             console.warn(`${lc} possibly a bottleneck here, getLocalIbGib only gets a single ibgib... (W: 2fd448a435480e6b128f6b8bcbef4826)`);
+            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: cfb9431f2fb851f24a6c88e80c3b3326)`); }
 
-            const resGet = await getFromSpace({ space: this.senderSpace, addr });
+            const resGet = await getFromSpace({ space: this.opts.senderSpace, addr });
 
             if (resGet.success && resGet.ibGibs && resGet.ibGibs.length === 1) {
                 const ibGib = resGet.ibGibs[0];
                 return ibGib;
             } else {
-                throw new Error(`couldn't get addr (${addr}) from local space ${this.senderSpace}. reason: ${resGet.errorMsg ?? 'unknown error (E: 926ef8bf4fcc299ab89dba34ea691a26)'} (E: d8a89807e471d3f8b938ab21df44cb26)`);
+                throw new Error(`couldn't get addr (${addr}) from local space ${this.opts.senderSpace}. reason: ${resGet.errorMsg ?? 'unknown error (E: 926ef8bf4fcc299ab89dba34ea691a26)'} (E: d8a89807e471d3f8b938ab21df44cb26)`);
             }
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);

package/src/sync/sync-saga-context/sync-saga-context-helpers.mts

@@ -111,13 +111,13 @@ export async function parseSyncSagaContextIb({
 /**
  * Creates new SyncSagaContext stone. Puts/registers in {@link localSpace}
  * immediately after creation.
- * 
+ *
  * @returns The context ibGib.
- * 
+ *
  * ## notes
- * 
+ *
  * the other ibgibs that are related to this context stone should already be
- * put/registered in {@link localSpace}. 
+ * put/registered in {@link localSpace}.
  */
 export async function createSyncSagaContext({
     sagaFrame,
@@ -138,7 +138,7 @@ export async function createSyncSagaContext({
             timestampMs,
         };
 
-        // Domain Payloads 
+        // Domain Payloads
         const payloadAddrsDomain = payloadIbGibsDomain ?
             payloadIbGibsDomain?.map(x => getIbGibAddr({ ibGib: x })) :
             undefined;
@@ -189,10 +189,19 @@ export async function createSyncSagaContext({
 }
 
 /**
- * move to sync-peer-helpers.mts as a pure function?
+ * Validates ONLY the {@link context} ibgib itself and saga frame/msg stone(s)
+ * ({@link SyncSagaContextIbGib_V1.sagaFrame}).
+ *
+ * Does NOT...
+ * * validate keystones (authn or authz)
+ * * validate domain payload ibgibs...
+ *   * intrinsically
+ *   * in relation to this context (addrs match up)
+ *
+ * @returns empty array if valid, else validation errors
  */
-export async function validateContext({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
-    const lc = `[${validateContext.name}]`;
+export async function validateContextAndSagaFrame({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
+    const lc = `[${validateContextAndSagaFrame.name}]`;
     try {
         if (logalot) { console.log(`${lc} starting... (I: 7797f8294bd8f7e5089cb722ad468226)`); }
 
@@ -226,4 +235,24 @@ export async function validateContext({ context }: { context: SyncSagaContextIbG
     } finally {
         if (logalot) { console.log(`${lc} complete.`); }
     }
+}
+
+
+/**
+ * validates the payload ibgibs ({@link SyncSagaContextIbGib_V1.payloadIbGibsDomain}) intrinsically
+ *
+ * @returns empty array if valid, else validation errors
+ */
+export async function validateContextDomainPayloadIbGibs({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
+    const lc = `[${validateContextDomainPayloadIbGibs.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 9f9fe835bcc80c75aa7fd6d887fc0826)`); }
+        console.error(`${lc} NAG MESSAGE (NOT THROWN). not implemented (E: bfe02ab36a227291a8f17ffc08f2ef26)`)
+        return [];
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
 }