@ibgib/core-gib 0.1.21 → 0.1.23

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

@@ -1,18 +1,39 @@
 /**
  * @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
  */
 
 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 { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.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 { 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 { 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 { getFromSpace } from '../../witness/space/space-helper.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,28 +50,94 @@ export abstract class SyncPeer_V1 extends LightWitnessBase_V1<SyncPeerData_V1, S
 
     protected lc: string = `[${SyncPeer_V1.name}]`;
 
+    public senderSpace: IbGibSpaceAny;
+    public senderTempSpace: IbGibSpaceAny;
+    public 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(senderSpace: IbGibSpaceAny, senderTempSpace: IbGibSpaceAny, initialData: SyncPeerData_V1, initialRel8ns?: SyncPeerRel8ns_V1) {
+        super(initialData, initialRel8ns);
+        this.senderSpace = senderSpace;
+        this.senderTempSpace = senderTempSpace;
+    }
+
+    async initialize(): Promise<void> {
+        this.payloadIbGibsDomainReceived$ = await newupSubject<IbGib_V1>();
+    }
+
+    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.
      */
-    async witness(arg: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
+    override async witness(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
         const lc = `${this.lc}[${this.witness.name}]`;
         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
+
+            // 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)
+
             // 1. PUSH: Ensure Request Data is available on Receiver
-            await this.pushContextGraph({ context: arg });
+            await this.pushContextGraph({ context }); // ???
 
             // 2. EXECUTE: Trigger Remote Processing
-            const response = await this.sendRequest(arg);
+            const response = await this.sendContextRequest(context);
 
             if (!response) {
                 if (logalot) { console.log(`${lc} No response from peer.`); }
                 return undefined;
             }
 
+            // at this point, we have received the response context, sync saga
+            // frame/msg stones, 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 });
 
@@ -65,45 +152,98 @@ 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 specific IbGib(s) (by address) from Remote to Local.
+     */
+    protected abstract pull(addrs: IbGibAddr[]): Promise<void>;
+
+
+
+    /**
+     * move to sync-peer-helpers.mts as a pure function?
+     */
+    protected async authenticateContext({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
+        const lc = `${this.lc}[${this.authenticateContext.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 2677a482dfa873dcd1aa04a3031ff826)`); }
+
+            console.error(`${lc} NAG ERROR (NOT THROWN): not implemented. // todo: authenticate  (v1 must have this after we get merge logic workflow going) (E: bc3a78f2dab18ab64c36d055a4b50526)`);
+
+            return [];
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
 
     /**
-     * Primitive: Pulls a specific IbGib (by address) from Remote to Local.
+     * move to sync-peer-helpers.mts as a pure function?
      */
-    protected abstract pull(addr: string): Promise<void>;
+    protected async authorizeContext({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
+        const lc = `${this.lc}[${this.authorizeContext.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 48c918b41ceec0cd489ca3b8819e6826)`); }
+
+            console.error(`${lc} NAG ERROR (NOT THROWN): not implemented. authorize business logic (v1 must have this, but later when we are working on admin vs. student)(E: bc3a78f2dab18ab64c36d055a4b50526)`);
+
+            return [];
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
 
     /**
      * 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 +251,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 +262,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,21 +323,55 @@ 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)`); }
     }
 
     /**
      * 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 abstract getLocalIbGib(addr: string): Promise<IbGib_V1 | undefined>;
+    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.`); }
+        }
+    }
 }

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

@@ -2,39 +2,48 @@
  * @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 { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
 
+import { GLOBAL_LOG_A_LOT } from '../../core-constants.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,
-    SyncSagaContextIb_V1, SyncSagaContextRel8ns_V1
+    SyncSagaContextData_V1, SyncSagaContextIbGib_V1, SyncSagaContextIb_V1,
+    SyncSagaContextRel8ns_V1,
 } from './sync-saga-context-types.mjs';
+import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
+import { putInSpace, registerNewIbGib } from '../../witness/space/space-helper.mjs';
+import { SyncIbGib_V1 } from '../sync-types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
 
 /**
  * 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.).
      */
-    sagaFrame: IbGib_V1;
+    sagaFrame: SyncIbGib_V1;
     /**
      * Session identity keystones.
      */
     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[];
+    /**
+     * we persist the context in the local/sender space (relative to our
+     * execution POV) right when we create it.
+     */
+    localSpace: IbGibSpaceAny;
 }
 
 /**
@@ -48,11 +57,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 +83,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;
@@ -91,42 +109,121 @@ export async function parseSyncSagaContextIb({
 }
 
 /**
- * Creates a new SyncSagaContext ibGib stone.
+ * 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}. 
  */
 export async function createSyncSagaContext({
-    cmd,
     sagaFrame,
     sessionKeystones,
-    payloadAddrs,
+    payloadIbGibsDomain,
+    localSpace,
 }: CreateSyncSagaContextOptions): Promise<SyncSagaContextIbGib_V1> {
+    const lc = `[${createSyncSagaContext.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 6b87bee313e811d1d2fc90e87fbec826)`); }
 
-    const data: SyncSagaContextData_V1 = {
-        cmd,
-    };
-    if (payloadAddrs && payloadAddrs.length > 0) {
-        data[SYNC_SAGA_PAYLOAD_ADDRS_REL8N_NAME] = payloadAddrs;
-    }
+        const date = new Date();
+        const timestamp = getTimestamp(date);
+        const timestampMs = date.getMilliseconds();
 
-    const rel8ns: SyncSagaContextRel8ns_V1 = {};
+        const data: SyncSagaContextData_V1 = {
+            timestamp,
+            timestampMs,
+        };
 
-    if (sagaFrame) {
-        rel8ns.sagaFrame = [getIbGibAddr(sagaFrame)];
-    }
-    if (sessionKeystones && sessionKeystones.length > 0) {
-        rel8ns.sessionKeystone = sessionKeystones.map(getIbGibAddr);
-    }
+        // 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(x => getIbGibAddr({ ibGib: x }));
+        }
 
-    // Generate standard ib
-    const ib = await getSyncSagaContextIb({ data });
+        // Generate standard ib
+        const ib = await getSyncSagaContextIb({ data });
 
-    const contextIbGib = await Factory_V1.stone<SyncSagaContextData_V1, SyncSagaContextRel8ns_V1>({
-        parentPrimitiveIb: SYNC_SAGA_CONTEXT_ATOM,
-        ib,
-        data,
-        rel8ns,
-    });
+        const contextIbGib = await Factory_V1.stone<SyncSagaContextData_V1, SyncSagaContextRel8ns_V1>({
+            parentPrimitiveIb: SYNC_SAGA_CONTEXT_ATOM,
+            ib,
+            data,
+            rel8ns,
+        }) as SyncSagaContextIbGib_V1;
 
-    return contextIbGib as SyncSagaContextIbGib_V1;
+        // put/register immediately. Note that contextIbGib at this point is
+        // pure DTO, i.e., only ib, gib, data, rel8ns props.
+        await putInSpace({ ibGib: contextIbGib, space: localSpace, });
+        await registerNewIbGib({
+            ibGib: contextIbGib,
+            space: localSpace,
+            fnBroadcast: undefined,
+        });
+
+        // Attach actual ibgibs for transport (not pure DTO now)
+        contextIbGib.sagaFrame = sagaFrame;
+        if (payloadIbGibsDomain && payloadIbGibsDomain.length > 0) {
+            contextIbGib.payloadIbGibsDomain = payloadIbGibsDomain;
+        }
+
+        return contextIbGib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
 }
+
+/**
+ * move to sync-peer-helpers.mts as a pure function?
+ */
+export async function validateContext({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
+    const lc = `[${validateContext.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 7797f8294bd8f7e5089cb722ad468226)`); }
+
+        const errors: string[] = [];
+
+        // validate just the context first. if this fails we return early.
+        const intrinsicErrors = await validateIbGibIntrinsically({ ibGib: context });
+        if (intrinsicErrors && intrinsicErrors.length > 0) {
+            intrinsicErrors.forEach(x => errors.push(x));
+            return errors; /* <<<< returns early */
+        }
+
+        if (context.sagaFrame) {
+
+        } else {
+            errors.push(`context.sagaFrame is falsy. (E: b4edd88f4963f493789f83b29ba2df26)`);
+        }
+
+        // validate the entire context graph intrinsically, including saga frame, stones, identity(s) (if applicable but not authentication, that will be done in a separate step)
+
+
+
+        // ensure the non-dto properties on the context object (i.e. props
+        // that are not ib, gib, data, or rel8ns) match the data in the
+        // context object
+
+        throw new Error(`not implemented (E: cb639658e1183fa6c8a4ebca023ba926)`);
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}