@ibgib/core-gib 0.1.25 → 0.1.27

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

@@ -2,20 +2,28 @@
  * @module SyncPeerInnerspace_V1
  */
 
-import { extractErrorMsg, unique } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { delay, extractErrorMsg, pretty, unique } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGib_V1, IbGibData_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { isDna } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../../../core-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 { getFromSpace, putInSpace, registerNewIbGib } from '../../../witness/space/space-helper.mjs';
 import { SyncSagaContextIbGib_V1, } from '../../sync-saga-context/sync-saga-context-types.mjs';
 import { SyncPeerInnerspaceData_V1, SyncPeerInnerspaceIbGib_V1, SyncPeerInnerspaceOptions, SyncPeerInnerspaceRel8ns_V1 } from './sync-peer-innerspace-types.mjs';
 import { MetaspaceService } from '../../../witness/space/metaspace/metaspace-types.mjs';
 import { SyncSagaCoordinator } from '../../sync-saga-coordinator.mjs';
 import { IbGibSpaceResultData } from '../../../witness/space/space-types.mjs';
 import { InitializeSyncPeerOpts } from '../sync-peer-types.mjs';
+import { getSyncSagaMessageFromFrame } from '../../sync-saga-message/sync-saga-message-helpers.mjs';
+import { SYNC_STAGE_VALID_VALUES, SyncStage } from '../../sync-constants.mjs';
+import { SyncSagaMessageAckData_V1, SyncSagaMessageCommitData_V1, SyncSagaMessageData_V1, SyncSagaMessageDeltaData_V1, SyncSagaMessageInitData_V1 } from '../../sync-saga-message/sync-saga-message-types.mjs';
+import { getExecutionContext, getSyncSagaFrameDependencyGraph, putInSpace_dnasThenNonDnas } from '../../sync-helpers.mjs';
+import { splitPerTjpAndOrDna, toDto } from '../../../common/other/ibgib-helper.mjs';
+import { SyncExecutionContext } from '../../sync-types.mjs';
 
 
 const logalot = GLOBAL_LOG_A_LOT || true;
@@ -101,69 +109,183 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<InitializeSyncPeerInnersp
         }
     }
 
-
-    protected async push(addrs: IbGibAddr[]): Promise<void> {
-        const lc = `${this.lc}[${this.push.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting... (I: 07bce80be18f3259b8a311ed9c4da926)`); }
-            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: e1efd1b364cc8a8d985b243878f71e26)`); }
-
-            // silly defensive checks because this has been a ridiculous development cycle
-            if (!this.opts.senderSpace) { throw new Error(`(UNEXPECTED) this.opts.senderSpace falsy? (E: 503e288168f5d297f4d4e028bc538826)`); }
-            if (!this.opts.receiverTempSpace) { throw new Error(`(UNEXPECTED) this.opts.receiverTempSpace falsy? (E: 0bd7c1a0ba4868ac7a260e15b504e826)`); }
-
-            await this.transfer({ addrs, from: this.opts.senderSpace, to: this.opts.receiverTempSpace });
-        } 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)`); }
-
-            if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: 5a72b83fc1a83bf0f81d19330f575626)`); }
-
-            // silly defensive checks because this has been a ridiculous development cycle
-            if (!this.opts.receiverSpace) { throw new Error(`(UNEXPECTED) this.opts.receiverSpace falsy? (E: bd2fdfa89ba4c89a185b68e9bb1f1c26)`); }
-            if (!this.opts.senderTempSpace) { throw new Error(`(UNEXPECTED) this.opts.senderTempSpace falsy? (E: b23fa55713f881493dac4a9835ac7326)`); }
-
-            await this.transfer({ addrs, from: this.opts.receiverSpace, to: this.opts.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}]`;
         try {
             if (!this.opts) { throw new Error(`(UNEXPECTED) this.opts falsy? (E: d8b1348e3233810128999596b1fa5826)`); }
 
-            const { receiverSpace, receiverCoordinator, receiverMetaspace } = this.opts;
+            const {
+                senderSpace, senderTempSpace,
+                receiverSpace, receiverCoordinator, receiverMetaspace,
+                receiverTempSpace
+            } = this.opts;
 
             if (logalot) { console.log(`${lc} starting...Context: ${getIbGibAddr({ ibGib: context })}`); }
 
-            // 0. Validate context (naive, not business logic validation)
+            const { sagaFrame } = context;
+
+            // The context has already been validated, authenticated and authorized at this point.
+
+            // #region sanity validation assertions
             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)`); }
+            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)`); }
+            // #endregion sanity validation assertions
+
+            // let localSpace: IbGibSpaceAny;
+            // let localTempSpace: IbGibSpaceAny;
+            // let remoteSpace: IbGibSpaceAny;
+            // let remoteTempSpace: IbGibSpaceAny;
+            // if (getExecutionContext({ sagaFrame: context.sagaFrame }) === SyncExecutionContext.sender) {
+            //     localSpace = senderSpace;
+            //     localTempSpace = senderTempSpace;
+            //     remoteSpace = receiverSpace;
+            //     remoteTempSpace = receiverTempSpace;
+            // } else {
+            //     localSpace = receiverSpace;
+            //     localTempSpace = receiverTempSpace;
+            //     remoteSpace = senderSpace;
+            //     remoteTempSpace = senderSpace;
+            // }
+
+            const { sagaIbGib: _alreadyHave, msgStones, identities } = await getSyncSagaFrameDependencyGraph({
+                sagaIbGib: sagaFrame,
+                localSpace: senderSpace,
+            });
+            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];
+            if (!msg.data) { throw new Error(`(UNEXPECTED) sync saga message ibgib.data falsy? (E: 61ec18743988ad3cbab2072d1dd69826)`); }
 
+            // send the context itself, then send the payload ibgibs separately.
+            // in this innerspace, this just means putting the control ibgibs
+            // first into the receiver durable space, then we will spin off a
+            // promise to put any payload ibgibs in the receiver temp space.
+            // We'll test a little latency also, to mimic a fuller, two-part
+            // sync peer to ensure that other code is acting as expected.
+
+            // we store inside out, meaning we do the dependencies first and
+            // then the higher-level dependents.
+            const payloadIbGibsControl = [
+                ...identities, msg, sagaFrame, context
+            ].map(x => toDto({ ibGib: x }));
+            await putInSpace({
+                ibGibs: payloadIbGibsControl,
+                space: receiverSpace,
+            });
+            // register yet??
+            for (const control of payloadIbGibsControl) {
+                await registerNewIbGib({
+                    ibGib: control,
+                    space: receiverSpace,
+                    fnBroadcast: undefined
+                });
+            }
 
-            // if we have push offer requests, start those.
+            if (context.payloadIbGibsDomain && context.payloadIbGibsDomain.length > 0) {
+                await putInSpace_dnasThenNonDnas({
+                    ibGibs: context.payloadIbGibsDomain,
+                    space: receiverTempSpace,
+                });
 
-            // send the context itself, then send the payload ibgibs separately.
+                // no need to register right now, because we're putting into the
+                // temp receiver space and we don't register until we commit
+                // const { mapWithTjp_NoDna, mapWithTjp_YesDna, mapWithoutTjps } =
+                //     splitPerTjpAndOrDna({ ibGibs: payload_NonDnas });
+            }
+
+            // at this time, the receiver has received the control ibgibs AND
+            // the payload ibgibs. so the receiver coordinator should be ready
+            // to do its thing.
 
+            const responseCtx = await receiverCoordinator.continueSync({
+                sagaContext: context,
+                metaspace: receiverMetaspace,
+                mySpace: receiverSpace,
+                myTempSpace: receiverTempSpace,
+            });
 
+            if (logalot) { console.log(`${lc} receiverCoordinator.continueSync responseCtx: ${responseCtx ? pretty(responseCtx) : 'undefined'} (I: fb2831decde1f2b3589021f85ab19126)`); }
+
+            if (!responseCtx) {
+                if (logalot) { console.log(`${lc} receiver produced undefined response context. (I: 2e1888ffc9e836689d5b171887c36d26)`); }
+                return undefined; /* <<<< returns early */
+            }
+
+            // at this point, we have received the full response from the
+            // receiver coordinator. That coordinator has put the control ibgibs
+            // in its durable space. Now we need to put the response's control
+            // ibgibs in the sender's durable space (register them??), spin off
+            // the process of any response payloads, and return the context.
+
+            // get control ibgibs from the receiver space...
+            const { msgStones: msgStonesResponse, identities: identitiesResponse } =
+                await getSyncSagaFrameDependencyGraph({
+                    sagaIbGib: responseCtx.sagaFrame,
+                    localSpace: receiverSpace,
+                });
+            if (msgStonesResponse.length !== 1) { throw new Error(`(UNEXPECTED) msgStonesResponse.length !== 1? we're only geared for a single msg stone that is always present (not 0, not greater than 1) (E: 2d3138ed130f1aca116551889483e826)`); }
+            const msgResponse = msgStonesResponse[0];
+            if (!msgResponse.data) { throw new Error(`(UNEXPECTED) sync saga message ibgib.data falsy? (E: 61ec18743988ad3cbab2072d1dd69826)`); }
+            const responsePayloadIbGibsControl = [
+                ...identities, msgResponse, responseCtx.sagaFrame, context
+            ].map(x => toDto({ ibGib: x }));
+            // ...put into sender's durable space
+            await putInSpace({
+                ibGibs: responsePayloadIbGibsControl,
+                space: senderSpace,
+            });
+            // register yet??
+            for (const control of responsePayloadIbGibsControl) {
+                await registerNewIbGib({
+                    ibGib: control,
+                    space: senderSpace,
+                    fnBroadcast: undefined
+                });
+            }
+
+            // spin off the payloads, as that may take a long time
+            const payloadIbGibsDomain_response = responseCtx.payloadIbGibsDomain;
+            if (payloadIbGibsDomain_response) {
+                new Promise<void>(async (resolve, reject) => {
+                    const lcPut = `${lc}[putPayloadsPromise]`;
+                    try {
+                        if (logalot) { console.log(`${lcPut} starting... (I: 4133e736b4c80d2cf94448b87b206826)`); }
+
+                        // 2 seconds...i want to see huge blocks of logs entries for this to see this happening
+                        const delayMs = 200;
+                        for (let i = 0; i < 10; i++) {
+                            console.warn(`${lc} ARTIFICIALLY DELAYING PAYLOADS TO MIMIC TRANSFER LATENCY. REMOVE THIS DELAY!! (W: 5e7b28f1daa82d955897e9d8cdb16f26)`)
+                            await delay(delayMs);
+                        }
+
+
+                        await putInSpace_dnasThenNonDnas({
+                            ibGibs: payloadIbGibsDomain_response,
+                            space: senderTempSpace,
+                        });
+
+                        if (logalot) { console.log(`${lcPut} complete.`); }
+                        resolve();
+                    } catch (error) {
+                        const errorMsg = `${lcPut} ${extractErrorMsg(error)}`;
+                        console.error(errorMsg);
+                        if (logalot) { console.log(`${lcPut} complete. (errored)`); }
+                        reject(errorMsg);
+                    }
+                }); // spin off
+
+                /**
+                 * the caller should be getting these from the observable.
+                 */
+                delete responseCtx.payloadIbGibsDomain;
+            }
 
-            throw new Error(`not implemented (E: 72840872e252d9f7380f1998b5a0c826)`);
+            return responseCtx;
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;

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

@@ -18,7 +18,7 @@ import { InitializeSyncPeerOpts, SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWit
 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 { validateContextAndSagaFrame } from '../sync-saga-context/sync-saga-context-helpers.mjs';
+import { authenticateContext, authorizeContext, 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;
@@ -178,34 +178,38 @@ export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts
             if (validationErrors.length > 0) {
                 throw new Error(`invalid context received. validationErrors: ${validationErrors} (E: 8b34c875c968af29bc433138e57a7826)`);
             }
-            const authenticationErrors = await this.authenticateContext({ context });
+            const authenticationErrors = await authenticateContext({ context });
             if (authenticationErrors.length > 0) {
                 throw new Error(`invalid context authentication. authenticationErrors: ${authenticationErrors} (E: da89da5ee1269aeb78952d475d607526)`);
             }
-            const authorizationErrors = await this.authorizeContext({ context });
+            const authorizationErrors = await 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);
+            await this.ensureReceiverTempSpace();
 
-            if (!response) {
-                if (logalot) { console.log(`${lc} No response from peer.`); }
-                return undefined;
-            }
+            // execute the transfer of control domain ibgibs & outgoing payload
+            // ibgibs...
+            const response = await this.sendContextRequest(context);
 
-            // 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 still be transferring. These will be published
-            // to this.payloadIbGibsDomainReceived$
+            if (response) {
+                // 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 still be transferring. These will be published
+                // to this.payloadIbGibsDomainReceived$
 
-            return response;
+                return response;
+            } else {
+                // response falsy. we could be done, or this could be an error.
+                if (logalot) { console.log(`${lc} No response from peer. this may be normal if we just sent the very last commit frame. (I: 1855b7728c8898e1f9c001f8170ba826)`); }
 
+                return undefined;
+            }
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;
@@ -215,75 +219,30 @@ export abstract class SyncPeer_V1<TInitializeOpts extends InitializeSyncPeerOpts
     }
 
     /**
+     * At this point, this is a validated, authenticated and authorized context
+     * to send.
+     *
      * This is responsible for:
      *
-     * * sending outgoing {@link context}, the sync saga frame and msg stone(s),
-     *   and identities...
+     * * physical 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$.
+     *   * BUT this should return as soon as the resultant context ibgib comes
+     *     back.
      *
-     * 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.
+     * So this returns the RESPONSE context, possibly BEFORE the response DOMAIN
+     * ibgibs have been completely received/streamed. The coordinator is
+     * responsible for awaiting this stream.
      *
-     * 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(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.`); }
-        }
-    }
-
-    /**
-     * move to sync-peer-helpers.mts as a pure function?
+     * @returns next sync saga context if another round, or undefined if we're
+     * done. (might throw if there's an error?)
      */
-    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.`); }
-        }
-    }
+    protected abstract sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined>;
 
     /**
      * Abstract accessor to get an IbGib from the Local space/store.

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

@@ -19,6 +19,7 @@ import {
 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';
+import { validateSyncSagaFrame } from '../sync-helpers.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -59,9 +60,10 @@ export async function getSyncSagaContextIb({
         if (!data) { throw new Error(`data required (E: 839d82138c234b3e89582855594191fe)`); }
 
         const payloadCount = data['@payloadAddrsDomain'] ? data['@payloadAddrsDomain'].length : 0;
-        // sync_sagacontext cmd
+
         const ib = [
             SYNC_SAGA_CONTEXT_ATOM,
+            data.sagaN,
             payloadCount,
         ].join(' ');
 
@@ -88,6 +90,7 @@ export async function parseSyncSagaContextIb({
         }
         const [
             atom,
+            sagaNStr,
             payloadCountStr,
         ] = parts;
 
@@ -95,13 +98,19 @@ export async function parseSyncSagaContextIb({
             throw new Error(`Atom mismatch. Expected ${SYNC_SAGA_CONTEXT_ATOM}. Got ${atom}. (E: 67d71fc0f8d04840b178652309f471f5)`);
         }
 
+        if (!sagaNStr) { throw new Error(`invalid ib. second piece should be sagaN but is falsy (E: 081ed475aeb8fe25a66f60466b2e5826)`); }
+        const sagaN = parseInt(sagaNStr);
+        if (isNaN(sagaN)) {
+            throw new Error(`sagaNStr is not a number. (E: 3d6b580d5a48c5e03ecec288896e2826)`);
+        }
+
         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 };
+        return { atom, sagaN, payloadCount };
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
         throw error;
@@ -129,6 +138,9 @@ export async function createSyncSagaContext({
     try {
         if (logalot) { console.log(`${lc} starting... (I: 6b87bee313e811d1d2fc90e87fbec826)`); }
 
+        if (!sagaFrame.data) { throw new Error(`(UNEXPECTED) sagaFrame.data falsy? (E: 04c49b4cccba6842a8b52e4c6f570726)`); }
+        if (!sagaFrame.data.n && sagaFrame.data.n !== 0) { throw new Error(`(UNEXPECTED) sagaFrame.data.n falsy and not 0? (E: 45b508da64a8b28428b11765d684b826)`); }
+
         const date = new Date();
         const timestamp = getTimestamp(date);
         const timestampMs = date.getMilliseconds();
@@ -136,6 +148,7 @@ export async function createSyncSagaContext({
         const data: SyncSagaContextData_V1 = {
             timestamp,
             timestampMs,
+            sagaN: sagaFrame.data.n,
         };
 
         // Domain Payloads
@@ -215,20 +228,27 @@ export async function validateContextAndSagaFrame({ context }: { context: SyncSa
         }
 
         if (context.sagaFrame) {
-
+            const sagaFrameErrors =
+                await validateSyncSagaFrame({ sagaIbGib: context.sagaFrame });
+            sagaFrameErrors.forEach(x => errors.push(x));
         } 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)
-
+        // if this is already invalid, we could have intrinsic validation errors, which are a non-starter.
+        if (errors.length > 0) { return errors; /* <<<< returns early */ }
 
+        // 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
+        // ~~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
+        // context object~~ NO. THIS WILL BE IN A SEPARATE FUNCTION.
+        // See `validateContextDomainPayloadIbGibs`
 
-        throw new Error(`not implemented (E: cb639658e1183fa6c8a4ebca023ba926)`);
+        // throw new Error(`not implemented (E: cb639658e1183fa6c8a4ebca023ba926)`);
+
+        console.error(`${lc} NAG ERROR MSG (NOT THROWN): not fully implemented yet (E: d574d85cb578637648ed403857f7a826)`);
+        return [];
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
         throw error;
@@ -239,7 +259,9 @@ export async function validateContextAndSagaFrame({ context }: { context: SyncSa
 
 
 /**
- * validates the payload ibgibs ({@link SyncSagaContextIbGib_V1.payloadIbGibsDomain}) intrinsically
+ * validates {@link SyncSagaContextIbGib_V1.payloadIbGibsDomain} intrinsically,
+ * and ensures that these payloadIbGibs also match the expected addrs in
+ * {@link SyncSagaContextData_V1}[{@link SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN}].
  *
  * @returns empty array if valid, else validation errors
  */
@@ -248,6 +270,44 @@ export async function validateContextDomainPayloadIbGibs({ context }: { context:
     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.`); }
+    }
+}
+
+/**
+ * move to sync-peer-helpers.mts as a pure function?
+ */
+export async function authenticateContext({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
+    const lc = `[${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.`); }
+    }
+}
+
+/**
+ * move to sync-peer-helpers.mts as a pure function?
+ */
+export async function authorizeContext({ context }: { context: SyncSagaContextIbGib_V1 }): Promise<string[]> {
+    const lc = `[${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)}`);

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

@@ -11,6 +11,10 @@ import { SYNC_SAGA_CONTEXT_ATOM } from './sync-saga-context-constants.mjs';
 
 export interface SyncSagaContextIb_V1 {
     atom: typeof SYNC_SAGA_CONTEXT_ATOM;
+    /**
+     * sagaFrame.data.n value
+     */
+    sagaN: number;
     /**
      * simple metadata count of data["@payloadAddrsDomain"]
      */
@@ -21,6 +25,10 @@ export interface SyncSagaContextIb_V1 {
  * Data payload for the Sync Saga Context.
  */
 export interface SyncSagaContextData_V1 extends IbGibData_V1 {
+    /**
+     * context's sagaFrame.data.n value
+     */
+    sagaN: number;
     /**
      * Payload data addresses for DOMAIN ibGibs (Timeline frames, user content).
      * Soft-linked via data property to avoid hard-linking graph dependencies.
@@ -35,7 +43,7 @@ export interface SyncSagaContextData_V1 extends IbGibData_V1 {
 export interface SyncSagaContextRel8ns_V1 extends IbGibRel8ns_V1 {
     /**
      * The primary Saga Frame being transported (Init, Ack, Delta, etc.).
-     * 
+     *
      * Should be a single addr.
      */
     sagaFrame: IbGibAddr[];
@@ -43,9 +51,9 @@ export interface SyncSagaContextRel8ns_V1 extends IbGibRel8ns_V1 {
     /**
      * The Ephemeral Session Keystone Identity used for this saga.
      * Required for validating the saga frame signature.
-     * 
+     *
      * ## notes
-     * 
+     *
      * This will be different for the sender and receiver, yes? hmm...
      * I think I need to put "sender" or "receiver" in the session keystone ib.
      */
@@ -59,7 +67,7 @@ export interface SyncSagaContextRel8ns_V1 extends IbGibRel8ns_V1 {
 export interface SyncSagaContextIbGib_V1 extends IbGib_V1<SyncSagaContextData_V1, SyncSagaContextRel8ns_V1> {
     /**
      * Domain ibgibs - OUTBOUND only.
-     * 
+     *
      * For inbound, the domain payload ibgibs are streamed via observable in the
      * peer.
      */
@@ -67,7 +75,7 @@ export interface SyncSagaContextIbGib_V1 extends IbGib_V1<SyncSagaContextData_V1
 
     /**
      * Reference to the actual sync saga frame that this context conveys.
-     * 
+     *
      * This frame's addr should be {@link SyncSagaContextRel8ns_V1.sagaFrame}.
      */
     sagaFrame: SyncIbGib_V1;