@ibgib/core-gib 0.1.21 → 0.1.22

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

@@ -0,0 +1,242 @@
+/**
+ * @module SyncPeerInnerspace_V1
+ */
+
+import { extractErrorMsg, unique } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+import { SYNC_ATOM, } from '../../sync-constants.mjs';
+import { IbGibSpaceAny } from '../../../witness/space/space-base-v1.mjs';
+import { SyncPeer_V1 } from '../sync-peer-v1.mjs';
+import { getFromSpace, putInSpace } from '../../../witness/space/space-helper.mjs';
+import { SyncSagaContextIbGib_V1, } from '../../sync-saga-context/sync-saga-context-types.mjs';
+import { createSyncSagaContext } from '../../sync-saga-context/sync-saga-context-helpers.mjs';
+import { SubjectWitness } from '../../../common/pubsub/subject/subject-types.mjs';
+import { newupSubject } from '../../../common/pubsub/subject/subject-helper.mjs';
+import { SyncPeerInnerspaceData_V1, SyncPeerInnerspaceIbGib_V1, SyncPeerInnerspaceOptions, SyncPeerInnerspaceRel8ns_V1 } from './sync-peer-innerspace-types.mjs';
+import { SYNC_PEER_INNERSPACE_ATOM } from './sync-peer-innerspace-constants.mjs';
+import { SyncPeerData_V1, SyncPeerRel8ns_V1 } from '../sync-peer-types.mjs';
+import { MetaspaceService } from '../../../witness/space/metaspace/metaspace-types.mjs';
+import { SyncSagaCoordinator } from '../../sync-saga-coordinator.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGibSpaceResultData } from '../../../witness/space/space-types.mjs';
+import { getSyncSagaDependencyGraph } from '../../sync-helpers.mjs';
+
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+const logalotControlDomain = true;
+const lcControlDomain = '[ControlDomain]';
+
+/**
+ * Concrete implementation of SyncPeer for local in-memory simulation (Innerspace to Innerspace).
+ * 
+ * Acts as the "Network" layer, transferring data between two local spaces and 
+ * executing the receiver's coordinator logic.
+ */
+export class SyncPeerInnerspace_V1 extends SyncPeer_V1 implements SyncPeerInnerspaceIbGib_V1 {
+
+    protected lc: string = `[${SyncPeerInnerspace_V1.name}]`;
+
+    public payloadIbGibsDomainReceived$!: SubjectWitness<IbGib_V1>;
+
+    private senderSpace: IbGibSpaceAny;
+    private senderTempSpace: IbGibSpaceAny;
+    private receiverCoordinator: SyncSagaCoordinator;
+    private receiverMetaspace: MetaspaceService;
+    private receiverSpace: IbGibSpaceAny;
+    private receiverTempSpace: IbGibSpaceAny;
+
+    override get classname(): string {
+        return SyncPeerInnerspace_V1.name;
+    }
+
+    constructor(
+        opts: SyncPeerInnerspaceOptions,
+        initialData: SyncPeerInnerspaceData_V1,
+        initialRel8ns?: SyncPeerInnerspaceRel8ns_V1,
+    ) {
+        super(initialData, initialRel8ns);
+        const {
+            senderSpace, senderTempSpace, receiverCoordinator,
+            receiverMetaspace, receiverSpace, receiverTempSpace
+        } = opts;
+
+        this.senderSpace = senderSpace;
+        this.senderTempSpace = senderTempSpace;
+        this.receiverCoordinator = receiverCoordinator;
+        this.receiverMetaspace = receiverMetaspace;
+        this.receiverSpace = receiverSpace;
+        this.receiverTempSpace = receiverTempSpace;
+    }
+
+    async initialize(): Promise<void> {
+        this.payloadIbGibsDomainReceived$ = await newupSubject<IbGib_V1>();
+    }
+
+    private async ensureReceiverTempSpace(): Promise<IbGibSpaceAny> {
+        if (!this.receiverTempSpace) {
+            const { receiverMetaspace } = this;
+
+            const uuid = crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36);
+            const tempSpaceName = `tmp_sync_recv_${uuid.substring(0, 8)}`;
+            const receiverTempSpace = await this.receiverMetaspace.createNewLocalSpace({
+                opts: {
+                    allowCancel: false,
+                    spaceName: tempSpaceName,
+                    getFnPrompt: this.receiverMetaspace.getFnPrompt!,
+                    logalot
+                }
+            });
+            if (!receiverTempSpace) { throw new Error(`(UNEXPECTED) receiverTempSpace falsy? couldn't create a temp space? (E: a6b8f86b0f58384b884a33b82924b826)`); }
+            await receiverTempSpace.initialized;
+            this.receiverTempSpace = receiverTempSpace;
+        }
+        return this.receiverTempSpace;
+    }
+
+    protected async getLocalIbGib(addr: string): Promise<IbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.getLocalIbGib.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 27b248cb9801eeb2386b71485389a826)`); }
+
+            console.warn(`${lc} possibly a bottleneck here, getLocalIbGib only gets a single ibgib... (W: 2fd448a435480e6b128f6b8bcbef4826)`);
+
+            const resGet = await getFromSpace({ space: this.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)`);
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected async push(addrs: IbGibAddr[]): Promise<void> {
+        const lc = `${this.lc}[${this.push.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 07bce80be18f3259b8a311ed9c4da926)`); }
+
+            // silly defensive checks because this has been a ridiculous development cycle
+            if (!this.senderSpace) { throw new Error(`(UNEXPECTED) this.senderSpace falsy? (E: 503e288168f5d297f4d4e028bc538826)`); }
+            if (!this.receiverSpace) { throw new Error(`(UNEXPECTED) this.receiverSpace falsy? (E: 0bd7c1a0ba4868ac7a260e15b504e826)`); }
+
+            await this.transfer({ addrs, from: this.senderSpace, to: this.receiverSpace });
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected async pull(addrs: IbGibAddr[]): Promise<void> {
+        const lc = `${this.lc}[${this.pull.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: b16a28ed0dc8f52f1838ee257d9b1126)`); }
+
+            // silly defensive checks because this has been a ridiculous development cycle
+            if (!this.receiverSpace) { throw new Error(`(UNEXPECTED) this.receiverSpace falsy? (E: bd2fdfa89ba4c89a185b68e9bb1f1c26)`); }
+            if (!this.senderTempSpace) { throw new Error(`(UNEXPECTED) this.senderTempSpace falsy? (E: b23fa55713f881493dac4a9835ac7326)`); }
+
+            await this.transfer({ addrs, from: this.receiverSpace, to: this.senderTempSpace });
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected async sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.sendContextRequest.name}]`;
+        const { receiverSpace, receiverCoordinator, receiverMetaspace } = this;
+
+        try {
+            if (logalot) { console.log(`${lc} starting...Context: ${getIbGibAddr({ ibGib: context })}`); }
+
+            // 0. Validate context (naive, not business logic validation)
+            if (!context.data) { throw new Error(`(UNEXPECTED) context.data falsy? (E: 1d2ac8a9b991d451e8900588057fe626)`); }
+            if (!context.rel8ns) { throw new Error(`(UNEXPECTED) context.rel8ns falsy? (E: 3508786f0d8880bcadd346282a807826)`); }
+            if (!context.rel8ns.sagaFrame) { throw new Error(`(UNEXPECTED) context.rel8ns.sagaFrame falsy? (E: ac06782ad538be406882605f0a83aa26)`); }
+            if (!context.sagaFrame) { throw new Error(`(UNEXPECTED) context.sagaFrame falsy? (E: 79cd98a6d9b88a591f4596c8bc58ff26)`); }
+
+            // validate the context, sagaFrame, and identity(s)
+            // persist the context, sagaframe, identity(s) ONLY in the receiver's durable space
+            // if sending domain ibgibs...
+            //   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
+            // analyze the response context
+            //   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, 
+            //   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)
+
+
+            throw new Error(`not implemented (E: 72840872e252d9f7380f1998b5a0c826)`);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Helper to copy single ibgib from A to B.
+     */
+    protected async transfer({
+        addrs,
+        from,
+        to
+    }: {
+        addrs: IbGibAddr[],
+        from: IbGibSpaceAny,
+        to: IbGibSpaceAny
+    }): Promise<void> {
+        const lc = `${this.lc}[${this.transfer.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: f1145dc75a461afc885efe984f08d426)`); }
+
+            console.error(`${lc} NAG ERROR (DOES NOT THROW): This needs to be adapted to be able to pull from multiple spaces. IOW, the 'from' param should be an array of spaces. This is because we need to be checking both durable and temp spaces when querying. (E: 823f3856b8b82ece080868e85ded0826)`)
+
+            // 1. Get from Source
+            const resGet = await getFromSpace({ space: from, addrs });
+            if (!resGet.success || !resGet.ibGibs || resGet.ibGibs.length !== addrs.length) {
+                if (!resGet.rawResultIbGib) { throw new Error(`(UNEXPECTED) resGet.rawResultIbGib falsy? (E: b829f827a378890bcf7dc3d41c908826)`); }
+                if (!resGet.rawResultIbGib.data) { throw new Error(`(UNEXPECTED) resGet.rawResultIbGib.data falsy? (E: 8d15341d8fa8fc96297425e3c6e39226)`); }
+                const data = resGet.rawResultIbGib.data as IbGibSpaceResultData;
+
+                throw new Error(`${lc} Failed to get all ${addrs} from source space ${from.ib}. resGet.errorMsg: ${resGet.errorMsg}. failed info: ${JSON.stringify(data)} (E: 4ed3383573382920c80054d7c1024626)`);
+            }
+            const ibGibs = resGet.ibGibs.concat();
+
+            // 2. Put in Dest
+            // Note: putInSpace handles existence check usually, or we can check.
+            const resPut = await putInSpace({ space: to, ibGibs });
+            if (resPut.success) {
+                console.error(`${lc} NAG ERROR: (SORT OF AN ERROR, DID NOT THROW): is the sync peer responsible for calling registerNewIbGib?? I'm not sure at this point if that is true, rather, I think that it probably is NOT responsible for this. But I'm putting this error msg as a nag message until this is resolved. (E: 00086833e294ee834800046801c47826) `);
+            } else {
+                throw new Error(`ERROR: successfully got addrs (${addrs}) from space (${from.ib}), BUT failed to put into space (${to.ib}). resPut.errorMsg: ${resPut.errorMsg}. timedOut: ${resPut.timedOut}. (E: c1044e14cc1db72d28a2240819dab826)`);
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+
+    }
+}

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

@@ -3,6 +3,7 @@
  */
 
 import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { SubjectWitness } from '../../common/pubsub/subject/subject-types.mjs';
 
 import { SyncSagaContextData_V1, SyncSagaContextIbGib_V1, SyncSagaContextRel8ns_V1 } from '../sync-saga-context/sync-saga-context-types.mjs';
 import { Witness_V1 } from '../../witness/witness-types.mjs';
@@ -11,7 +12,10 @@ import { Witness_V1 } from '../../witness/witness-types.mjs';
  * Data for the SyncPeer witness.
  */
 export interface SyncPeerData_V1 extends IbGibData_V1 {
-    // Add specific settings for Sync Peer if needed (e.g. timeout, retry policy)
+    /**
+     * Concrete peer instance
+     */
+    classname: string;
 }
 
 /**
@@ -40,4 +44,12 @@ export interface SyncPeerWitness extends Witness_V1<
     SyncPeerRel8ns_V1
 > {
     // witness(arg: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined>;
+
+    /**
+     * 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.
+     */
+    payloadIbGibsDomainReceived$: SubjectWitness<IbGib_V1>;
 }

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

@@ -5,14 +5,18 @@
 import { extractErrorMsg } 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 { SubjectWitness } from '../../common/pubsub/subject/subject-types.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
-import { SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME } from '../sync-constants.mjs';
+import { SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from '../sync-constants.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 { LightWitnessBase_V1 } from '../../witness/light-witness-base-v1.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT || true;
+const logalotControlDomain = true;
+const lcControlDomain = '[ControlDomain]';
 
 /**
  * Abstract witness for talking to a Sync Peer (e.g. Remote Node or Local Simulator).
@@ -29,6 +33,17 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
 
     protected lc: string = `[${SyncPeer_V1.name}]`;
 
+    abstract payloadIbGibsDomainReceived$: SubjectWitness<IbGib_V1>;
+
+    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)`); }
+        return this.data.classname;
+    }
+
+    constructor(initialData: SyncPeerData_V1, initialRel8ns?: SyncPeerRel8ns_V1) {
+        super(initialData, initialRel8ns);
+    }
     /**
      * Witness the synchronization context (Send/Receive).
      * 
@@ -40,11 +55,13 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
         try {
             if (logalot) { console.log(`${lc} starting...`); }
 
+            if (logalot) { console.log(`${lc} starting...`); }
+
             // 1. PUSH: Ensure Request Data is available on Receiver
             await this.pushContextGraph({ context: arg });
 
             // 2. EXECUTE: Trigger Remote Processing
-            const response = await this.sendRequest(arg);
+            const response = await this.sendContextRequest(arg);
 
             if (!response) {
                 if (logalot) { console.log(`${lc} No response from peer.`); }
@@ -65,45 +82,58 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
     }
 
     /**
-     * Primitive: Transmits the Context IbGib itself to the Peer.
+     * Transmits the Context IbGib itself to the Peer.
      */
-    protected abstract sendRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined>;
+    protected abstract sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined>;
 
     /**
-     * Primitive: Pushes a specific IbGib (by address) from Local to Remote.
-     * Should handle identifying if the remote already has it (optimization) or just put it.
+     * 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.
      */
-    protected abstract push(addr: string): Promise<void>;
+    protected abstract push(addrs: IbGibAddr[]): Promise<void>;
 
     /**
-     * Primitive: Pulls a specific IbGib (by address) from Remote to Local.
+     * Primitive: Pulls specific IbGib(s) (by address) from Remote to Local.
      */
-    protected abstract pull(addr: string): Promise<void>;
+    protected abstract pull(addrs: IbGibAddr[]): Promise<void>;
 
     /**
      * 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 });
-        await this.push(contextAddr);
+        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) {
-            await this.push(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) await this.push(addr);
+                    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) await this.push(addr);
+                    for (const addr of idAddrs) {
+                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Identity -> ${addr} (I: 6c7d8e9f0a1b2c3d)`); }
+                        await this.push([addr]);
+                    }
                 }
             }
         }
@@ -111,7 +141,8 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
         // C. Push Session Identity
         const sessionKeystoneAddr = context.rel8ns?.sessionKeystone?.[0];
         if (sessionKeystoneAddr) {
-            await this.push(sessionKeystoneAddr);
+            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PUSH CONTROL: Session Keystone -> ${sessionKeystoneAddr} (I: 7d8e9f0a1b2c3d4e)`); }
+            await this.push([sessionKeystoneAddr]);
         }
 
         // D. Push Payloads (Deep/Soft)
@@ -121,36 +152,60 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
         // 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.
-        const payloadAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME];
-        if (payloadAddrs) {
-            for (const addr of payloadAddrs) {
-                await this.push(addr); // Assumed shallow/flat per user instruction
+
+        // 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 });
-        await this.pull(contextAddr);
+        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) {
-            await this.pull(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) await this.pull(addr);
+                    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) await this.pull(addr);
+                    for (const addr of idAddrs) {
+                        if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Identity <- ${addr} (I: e4f5a6b7c8d9e0f1)`); }
+                        await this.pull([addr]);
+                    }
                 }
             }
         }
@@ -158,16 +213,27 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
         // C. Pull Session Identity
         const sessionKeystoneAddr = context.rel8ns?.sessionKeystone?.[0];
         if (sessionKeystoneAddr) {
-            await this.pull(sessionKeystoneAddr);
+            if (logalotControlDomain) { console.log(`${lc}${lcControlDomain} PULL CONTROL: Session Keystone <- ${sessionKeystoneAddr} (I: f5a6b7c8d9e0f1a2)`); }
+            await this.pull([sessionKeystoneAddr]);
         }
 
         // D. Pull Payloads
-        const payloadAddrs = context.data?.[SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME];
-        if (payloadAddrs) {
-            for (const addr of payloadAddrs) {
-                await this.pull(addr);
+        // 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)`); }
     }
 
     /**

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

@@ -2,27 +2,24 @@
  * @module sync saga context helpers
  */
 
-import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { extractErrorMsg, getTimestamp } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { IbGib_V1, } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { Ib } from '@ibgib/ts-gib/dist/types.mjs';
 
 import { SYNC_SAGA_CONTEXT_ATOM } from './sync-saga-context-constants.mjs';
-import { SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME } from '../sync-constants.mjs';
+import { SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from '../sync-constants.mjs';
 import {
-    SyncSagaContextCmd, SyncSagaContextData_V1, SyncSagaContextIbGib_V1,
+    SyncSagaContextData_V1, SyncSagaContextIbGib_V1,
     SyncSagaContextIb_V1, SyncSagaContextRel8ns_V1
 } from './sync-saga-context-types.mjs';
+import { getTimestampInfo } from '../../common/other/ibgib-helper.mjs';
 
 /**
  * Options for creating a SyncSagaContext ibgib.
  */
 export interface CreateSyncSagaContextOptions {
-    /**
-     * Optional command string (e.g. 'process').
-     */
-    cmd?: SyncSagaContextCmd | string;
     /**
      * The main saga frame (Init, Ack, etc.).
      */
@@ -32,9 +29,10 @@ export interface CreateSyncSagaContextOptions {
      */
     sessionKeystones?: IbGib_V1[];
     /**
-     * Payload addresses (strings) for bulk data.
+     * Domain payload ibgibs when the sync saga frame includes actual domain
+     * payloads to send, e.g., in a Delta frame.
      */
-    payloadAddrs?: string[];
+    payloadIbGibsDomain?: IbGib_V1[];
 }
 
 /**
@@ -48,11 +46,12 @@ export async function getSyncSagaContextIb({
     const lc = `[${getSyncSagaContextIb.name}]`;
     try {
         if (!data) { throw new Error(`data required (E: 839d82138c234b3e89582855594191fe)`); }
-        const cmd = data.cmd || 'default';
+
+        const payloadCount = data['@payloadAddrsDomain'] ? data['@payloadAddrsDomain'].length : 0;
         // sync_sagacontext cmd
         const ib = [
             SYNC_SAGA_CONTEXT_ATOM,
-            cmd
+            payloadCount,
         ].join(' ');
 
         return ib;
@@ -73,17 +72,25 @@ export async function parseSyncSagaContextIb({
     const lc = `[${parseSyncSagaContextIb.name}]`;
     try {
         const parts = ib.split(' ');
-        if (parts.length < 2) {
-            throw new Error(`Invalid sync saga context ib. Expected at least 2 parts [atom cmd]. Got ${parts.length}. (E: 8b06c88820c74f5fb9f21f148459422a)`);
+        if (parts.length !== 2) {
+            throw new Error(`Invalid sync saga context ib. Expected at least 2 parts [atom, payloadCount]. Got ${parts.length}. (E: 8b06c88820c74f5fb9f21f148459422a)`);
         }
-        const [atom, ...rest] = parts;
-        const cmd = rest.join(' '); // cmd might have spaces if it's not a strict enum? but usually single word key.
+        const [
+            atom,
+            payloadCountStr,
+        ] = parts;
 
         if (atom !== SYNC_SAGA_CONTEXT_ATOM) {
             throw new Error(`Atom mismatch. Expected ${SYNC_SAGA_CONTEXT_ATOM}. Got ${atom}. (E: 67d71fc0f8d04840b178652309f471f5)`);
         }
 
-        return { atom, cmd };
+        if (!payloadCountStr) { throw new Error(`invalid ib. second piece should be payloadCount but is falsy (E: 0bb7580793d800ca02227828a7294826)`); }
+        const payloadCount = parseInt(payloadCountStr);
+        if (isNaN(payloadCount)) {
+            throw new Error(`payloadCountStr is not a number. (E: 49457814282a44069871630987588722)`);
+        }
+
+        return { atom, payloadCount };
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
         throw error;
@@ -96,26 +103,32 @@ export async function parseSyncSagaContextIb({
  * @returns The context ibGib.
  */
 export async function createSyncSagaContext({
-    cmd,
     sagaFrame,
     sessionKeystones,
-    payloadAddrs,
+    payloadIbGibsDomain,
 }: CreateSyncSagaContextOptions): Promise<SyncSagaContextIbGib_V1> {
 
+    const date = new Date();
+    const timestamp = getTimestamp(date);
+    const timestampMs = date.getMilliseconds();
+
     const data: SyncSagaContextData_V1 = {
-        cmd,
+        timestamp,
+        timestampMs,
     };
-    if (payloadAddrs && payloadAddrs.length > 0) {
-        data[SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME] = payloadAddrs;
-    }
-
-    const rel8ns: SyncSagaContextRel8ns_V1 = {};
 
-    if (sagaFrame) {
-        rel8ns.sagaFrame = [getIbGibAddr(sagaFrame)];
+    // Domain Payloads 
+    const payloadAddrsDomain = payloadIbGibsDomain ? payloadIbGibsDomain?.map(x => getIbGibAddr({ ibGib: x })) : undefined;
+    if (payloadAddrsDomain && payloadAddrsDomain.length > 0) {
+        data[SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN] = payloadAddrsDomain;
     }
+
+    // rel8ns should always have saga frame, sometimes have keystone
+    const rel8ns: SyncSagaContextRel8ns_V1 = {
+        sagaFrame: [getIbGibAddr({ ibGib: sagaFrame })],
+    };
     if (sessionKeystones && sessionKeystones.length > 0) {
-        rel8ns.sessionKeystone = sessionKeystones.map(getIbGibAddr);
+        rel8ns.sessionKeystone = sessionKeystones.map(x => getIbGibAddr({ ibGib: x }));
     }
 
     // Generate standard ib
@@ -126,7 +139,12 @@ export async function createSyncSagaContext({
         ib,
         data,
         rel8ns,
-    });
+    }) as SyncSagaContextIbGib_V1;
+
+    // Attach actual ibgibs for transport 
+    if (payloadIbGibsDomain && payloadIbGibsDomain.length > 0) {
+        contextIbGib.payloadIbGibsDomain = payloadIbGibsDomain;
+    }
 
-    return contextIbGib as SyncSagaContextIbGib_V1;
+    return contextIbGib;
 }