@ibgib/core-gib 0.1.26 → 0.1.28

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

@@ -6,6 +6,7 @@ import { SyncStage } from "../sync-constants.mjs";
 import { SyncMode, SyncConflictStrategy, } from "../sync-types.mjs";
 import { SYNC_SAGA_MSG_ATOM } from "./sync-saga-message-constants.mjs";
 import type { getDeltaDependencyGraph } from '../../common/other/graph-helper.mjs';
+import type { SyncSagaContextIbGib_V1, SyncSagaContextData_V1 } from '../sync-saga-context/sync-saga-context-types.mjs';
 
 export interface SyncSagaMessageIb_V1 {
     atom: typeof SYNC_SAGA_MSG_ATOM;
@@ -38,7 +39,7 @@ export interface SyncSagaMessageIbGib_V1 extends IbGib_V1<SyncSagaMessageData_V1
 
 /**
  * The "Hello" of the sync protocol.
- * 
+ *
  * Exchanges knowledge vectors (what I have) and identity (who I am).
  */
 export interface SyncSagaMessageInitData_V1 extends SyncSagaMessageData_V1 {
@@ -47,7 +48,7 @@ export interface SyncSagaMessageInitData_V1 extends SyncSagaMessageData_V1 {
     /**
      * Map of TJP (Temporal Joint Point) to latest known ibGibAddr.
      * Use this to calculate what is missing (Delta).
-     * 
+     *
      * IOW, this is a map of the starting and end points of an ibGib's timeline.
      */
     knowledgeVector: { [tjp: string]: IbGibAddr };
@@ -67,14 +68,14 @@ export interface SyncSagaMessageInitData_V1 extends SyncSagaMessageData_V1 {
 
     /**
      * This is also in the sync saga ibgib itself now...
-     * 
+     *
      * @see {@link SyncOptions.conflictStrategy}
      */
     conflictStrategy?: SyncConflictStrategy;
 }
 
 /**
- * When an endpoing doesn't have a timeline or some part of it, then this info 
+ * When an endpoing doesn't have a timeline or some part of it, then this info
  * contains sufficient information for the other endpoint to know what addrs to
  * send.
  */
@@ -92,9 +93,9 @@ export interface SyncSagaRequestAddrInfo {
     /**
      * If this is truthy, then we already have something from this timeline and
      * this will be the latest addr in that timeline.
-     * 
+     *
      * If falsy, then we are requesting the entire timeline be sent.
-     * 
+     *
      * This is to be used to calculate the delta graph.
      * @see {@link getDeltaDependencyGraph}
      */
@@ -145,31 +146,19 @@ export interface SyncSagaConflictInfo {
 export interface SyncSagaMessageAckData_V1 extends SyncSagaMessageData_V1 {
     stage: typeof SyncStage.ack;
     deltaRequestAddrInfos: SyncSagaRequestAddrInfo[];
-    pushOfferInfos: SyncSagaPushOfferInfo[];
     /**
-     * Map of group keys (TJP addr/constant addr) to list of known addresses
-     * in that timeline.
-     * 
-     * This will be used by Sender to calculate differential payloads. So 
-     * when the sender goes to get the dependency graph of its tip ibgib,
-     * it can skip all of the addrs in this.
-     * 
-     * For example, say sender has A^5 and receiver only has A^3. Sender 
-     * will see in this map { [A^0]: [A^0, A^1, A^2, A^3] } and know that
-     * it needs all of the dependencies of A^5 (including A^4), but it does
-     * NOT need to send A^0-A^3 (and dependencies) because receiver already has
-     * these.
-     * 
-     * ## notes
-     * 
-     * I dislike this name in my rewrite/cleanup of this algorithm. However, I'm
-     * keeping it and am using it right now in handleInitFrame for including
-     * the receiver's latest addr/tip for the deltaReqAddrs. But really, I should 
-     */
-    // knowledgeVector?: { [tjpAddr: string]: string[] };
+     * Infos regarding ibgibs that the receiver (generator of this ack)
+     * knows/believes that the sender does NOT have (after looking at knowledge
+     * vector of sender).
+     *
+     * This includes addrs that will correspond to the context.payloadAddrsDomain
+     *
+     * ## note
+     */
+    pushOfferInfos: SyncSagaPushOfferInfo[];
     /**
      * List of identified conflicts.
-     * 
+     *
      * If present, the Sender should use the `timelineAddrs` (Receiver's
      * history) to compute the LCA and delta requirements for merging.
      */
@@ -178,22 +167,28 @@ export interface SyncSagaMessageAckData_V1 extends SyncSagaMessageData_V1 {
 
 /**
  * The "Body" of the sync protocol. Carries the manifests of data to be
- * transferred. 
- * 
+ * transferred.
+ *
  * If any {@link payloadAddrsDomain} exist, then these will be populated in the
  * {@link SyncSagaContextIbGib_V1}.
  */
 export interface SyncSagaMessageDeltaData_V1 extends SyncSagaMessageData_V1 {
     stage: typeof SyncStage.delta;
-    requests?: string[];
+    deltaRequestAddrInfos?: SyncSagaRequestAddrInfo[];
     /**
-     * Flag indicating the sender has no further requests or payloads 
+     * Flag indicating the sender has no further requests or payloads
      * and is ready to commit the transaction.
      */
     proposeCommit?: boolean;
     /**
      * Domain ibgib addresses (actual user data being synced).
      * These go to tempSpace ONLY until final commit.
+     *
+     * NOTE: There is also a payloadAddrsDomain on the actual context itself on
+     * {@link SyncSagaContextData_V1}.
+     * NOTE: There is also payload info in {@link SyncSagaMessageAckData_V1}
+     * in {@link SyncSagaMessageAckData_V1.pushOfferInfos}. Not quite as elegant
+     * as I want it to be but there ya go.
      */
     payloadAddrsDomain?: string[];
 }

package/src/sync/sync-types.mts

@@ -9,7 +9,7 @@ import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
 import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
 import { SyncPeerWitness } from "./sync-peer/sync-peer-types.mjs";
 import { FlatIbGibGraph } from "../common/other/graph-types.mjs";
-import { SyncSagaConflictInfo } from "./sync-saga-message/sync-saga-message-types.mjs";
+import { SyncSagaConflictInfo, SyncSagaMessageIbGib_V1 } from "./sync-saga-message/sync-saga-message-types.mjs";
 
 
 // #region SyncMode
@@ -54,17 +54,53 @@ export function isValidSyncConflictStrategy(strategy: string): strategy is SyncC
 }
 // #endregion SyncConflictStrategy
 
+// #region SyncExecutionContext
+export const SYNC_EXECUTION_CONTEXT_SENDER = 'sender';
+export const SYNC_EXECUTION_CONTEXT_RECEIVER = 'receiver';
+export type SyncExecutionContext =
+    | typeof SYNC_EXECUTION_CONTEXT_SENDER
+    | typeof SYNC_EXECUTION_CONTEXT_RECEIVER
+    ;
+/**
+ * if the current code execution is executing on the original sender (the
+ * initiator of the sync saga operation) or the other party, the "receiver" (the
+ * one responding).
+ *
+ * This is driven by looking at the latest value of `sagaFrame.data.n` value.
+ *
+ * NOTE: This is not to be confused with the sync saga context ibgib, which is
+ * something else entirely. That is the transport wrapper ibgib around the saga.
+ * this is strictly the enum for where the code is executing.
+ */
+export const SyncExecutionContext = {
+    /**
+     * The current code is executing on the initial location that started the
+     * sync.
+     */
+    sender: SYNC_EXECUTION_CONTEXT_SENDER,
+    /**
+     * The current code is executing on the receiving end, which is either a
+     * physically different location or is the logical "receiver" of an
+     * in-memory sync execution.
+     */
+    receiver: SYNC_EXECUTION_CONTEXT_RECEIVER,
+} satisfies { [key in SyncExecutionContext]: SyncExecutionContext };
+export const SYNC_EXECUTION_CONTEXT_VALID_VALUES = Object.values(SyncExecutionContext);
+export function isValidSyncExecutionContext(executionContext: string): executionContext is SyncExecutionContext {
+    return SYNC_EXECUTION_CONTEXT_VALID_VALUES.includes(executionContext as SyncExecutionContext);
+}
+// #endregion SyncConflictStrategy
+
 export interface NextSagaFrameInfo_Frame {
     frame: SyncIbGib_V1;
     payloadIbGibsDomain?: IbGib_V1[];
-    // conflictInfos?: SyncSagaConflictInfo;
-    responseWasNull?: undefined;
+    sagaComplete?: undefined;
 }
-export interface NextSagaFrameInfo_Null {
-    frame: never;
+export interface NextSagaFrameInfo_SagaComplete {
+    frame?: never;
     payloadIbGibsDomain?: never;
     conflictInfos?: never;
-    responseWasNull: true;
+    sagaComplete: true;
 }
 /**
  * Result of handling a saga frame.
@@ -75,7 +111,7 @@ export interface NextSagaFrameInfo_Null {
  * defined, thus the discriminated union type.
  */
 export type NextSagaFrameInfo =
-    NextSagaFrameInfo_Frame | NextSagaFrameInfo_Null;
+    NextSagaFrameInfo_Frame | NextSagaFrameInfo_SagaComplete;
 
 
 export interface HandleSagaResponseContextResult_Base {
@@ -170,7 +206,8 @@ export interface SyncSagaInfo {
 
 export interface SyncSagaFrameDependencyGraph {
     sagaIbGib: SyncIbGib_V1;
-    msgStones: IbGib_V1[];
+    // msgStones: IbGib_V1[];
+    msgStones: SyncSagaMessageIbGib_V1[];
     identities: KeystoneIbGib_V1[];
 }