@ibgib/core-gib 0.1.12 → 0.1.14

package/src/sync/sync-saga-coordinator.mts

@@ -2,104 +2,51 @@ import {
     extractErrorMsg,
     getUUID, // so our uuid's are uniform across all ibgib code
     getTimestamp, // so our timestamp strings are uniform
-    getTimestampInTicks // so our timestamp in ticks as a string are uniform
+    getTimestampInTicks, // so our timestamp in ticks as a string are uniform
+    pretty,
+    clone
 } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
 import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
 import { splitPerTjpAndOrDna, getTimelinesGroupedByTjp } from "../common/other/ibgib-helper.mjs";
 import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
-import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { IbGib_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
 import { isPrimitive } 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 { putInSpace, lockSpace, unlockSpace, getSpaceArgMetadata, getLatestAddrs } from "../witness/space/space-helper.mjs";
+import { putInSpace, lockSpace, unlockSpace, getSpaceArgMetadata, getLatestAddrs, getFromSpace } from "../witness/space/space-helper.mjs";
 import { KeystoneIbGib_V1 } from "../keystone/keystone-types.mjs";
 import { KeystoneService_V1 } from "../keystone/keystone-service-v1.mjs";
-import { SyncStage, SYNC_ATOM } from "./sync-constants.mjs";
+import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
+import { SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME } from "./sync-constants.mjs";
+import { appendToTimeline, createTimeline } from "../timeline/timeline-api.mjs";
 import {
     SyncData_V1, SyncIbGib_V1, SyncInitData, SyncDeltaData, SyncCommitData,
+    SyncConflictStrategy, SyncOptions,
+    SyncMode,
 } from "./sync-types.mjs";
-import { getSyncIb } from "./sync-helpers.mjs";
+import { getSyncIb, isPastFrame } from "./sync-helpers.mjs";
 import { getDependencyGraph } from "../common/other/graph-helper.mjs";
-
-const logalot = GLOBAL_LOG_A_LOT;
-
-export interface SyncOptions {
-    /**
-     * The space containing the data we want to send.
-     */
-    source: IbGibSpaceAny;
-    /**
-     * The space receiving the data.
-     */
-    dest: IbGibSpaceAny;
-    /**
-     * The identity authorizing this sync.
-     */
-    identity: KeystoneIbGib_V1;
-    /**
-     * The secret for the identity (to sign the commit).
-     */
-    identitySecret: string;
-}
+import {
+    SyncSagaMessageData_V1,
+    SyncSagaMessageInitData_V1,
+    SyncSagaMessageAckData_V1,
+    SyncSagaMessageDeltaData_V1,
+    SyncSagaMessageCommitData_V1
+} from "./sync-saga-message/sync-saga-message-types.mjs";
+import { getSyncSagaMessageIb } from "./sync-saga-message/sync-saga-message-helpers.mjs";
+import { SYNC_SAGA_MSG_ATOM } from "./sync-saga-message/sync-saga-message-constants.mjs";
+import { Subject_V1 } from "../common/pubsub/subject/subject-v1.mjs";
+import { SyncSagaInfo } from "./sync-types.mjs";
+import { SyncPeerWitness } from "./sync-peer/sync-peer-types.mjs";
+import { SyncSagaContextIbGib_V1, SyncSagaContextCmd } from "./sync-saga-context/sync-saga-context-types.mjs";
+import { createSyncSagaContext } from "./sync-saga-context/sync-saga-context-helpers.mjs";
+
+
+const logalot = GLOBAL_LOG_A_LOT || true;
 
 /**
  * Orchestrates the synchronization process between two spaces (Source and Destination).
- *
- * ## Architecture: Dependency Graph Synchronization
- *
- * Instead of a naive file-by-file sync or a holistic "Space" sync, this coordinator operates
- * on a **Dependency Graph** derived from specific "Domain Roots" (e.g., a specific tag,
- * folder, or application root).
- *
- * ### Workflow Pipeline
- *
- * 1.  **Graph Generation**:
- *     *   Generates a `FlatIbGibGraph` using `getDependencyGraph({ live: true })` starting
- *         from the provided `domainIbGibs`.
- *     *   This ensures we capture the *latest* reachable state of all relevant timelines.
- *
- * 2.  **Classification (`splitPerTjpAndOrDna`)**:
- *     *   **Stones**: Immutable, non-living ibGibs (no TJP/DNA). Trivial to sync (copy if missing).
- *     *   **Living**: Evolving timelines (TJP + DNA). Complex to sync (require ordering & merging).
- *
- * 3.  **Timeline Ordering (`getTimelinesGroupedByTjp`)**:
- *     *   Living ibGibs are grouped into timelines.
- *     *   A "Timeline Dependency Graph" is built. Use Case: If a Comment Timeline refers to a
- *         Post Timeline, the Post Timeline must be synced *before* the Comment Timeline to
- *         ensure referential integrity at the destination.
- *     *   **Topological Sort** determines the execution order. Circular dependencies are
- *         treated as siblings.
- *
- * 4.  **Saga Execution ("Smart Coordinator, Dumb Space")**:
- *     *   The Coordinator (running on the Client/Source) drives the entire process via a
- *         "Pull-Merge-Push" strategy to resolve conflicts.
- *
- *     *   **Phase 1: Knowledge Exchange (Init)**
- *         *   Generates a "Knowledge Vector" (Map<Tjp, LatestAddr>) of the Source's graph.
- *         *   Sends `SyncStage.Init` to Dest.
- *         *   Dest responds with its own Knowledge Vector for overlapping timelines.
- *
- *     *   **Phase 2: Gap Analysis & Conflict Resolution**
- *         *   Coordinator compares Source vs. Dest knowledge.
- *         *   **Fast-Forward**: Source is strictly ahead of Dest. Mark new frames for PUSH.
- *         *   **Fast-Backward**: Dest is strictly ahead of Source. Mark frames for PULL (to update Local).
- *         *   **Conflict/Divergence**: Both have new frames from a common ancestor.
- *             *   **LOCK**: `lockSpace({ scope: tjpGib })` on Dest to prevent race conditions.
- *             *   **PULL**: Download conflicting branch from Dest.
- *             *   **MERGE**: Execute merge logic locally (creating a new merge frame `A_merge`).
- *             *   **PUSH**: Mark `A_merge` (and dependencies) for PUSH.
- *             *   **UNLOCK**: Release Dest lock.
- *
- *     *   **Phase 3: Batch Streaming (Delta)**
- *         *   **Stones**: Batch `putInSpace` all missing "Stone" ibGibs first.
- *         *   **Timelines**: Batch `putInSpace` Living Timelines in topological order.
- *         *   *Note*: The `SyncFrame` (Init/Delta/Commit) tracks protocol state, but data transfer
- *             happens via standard `putInSpace`.
- *
- *     *   **Phase 4: Commit**
- *         *   Update Local Index (register new latests).
- *         *   Send `SyncStage.Commit` to Dest to finalize session.
  */
 export class SyncSagaCoordinator {
     protected lc: string = `[${SyncSagaCoordinator.name}]`;
@@ -109,214 +56,341 @@ export class SyncSagaCoordinator {
     ) { }
 
     /**
-     * Executes a synchronization saga.
-     *
-     * @param opts.source The local space (Client) driving the sync.
-     * @param opts.dest The remote space (Server/Other Peer) to sync with.
-     * @param opts.identity The Keystone Identity performing the sync.
-     * @param opts.domainIbGibs The root ibGibs that define the scope of the sync (the "Dependency Graph").
-     * @param opts.identitySecret Optional secret if needed (usually handled by `keystone` service).
+     * Executes a synchronization saga using the Symmetric Sync Protocol.
      */
     async sync({
-        source,
-        dest,
-        identity,
+        peer,
+        localSpace,
+        metaspace,
+        primaryIdentity,
+        primaryIdentitySecret,
         domainIbGibs,
-        identitySecret
     }: {
-        source: IbGibSpaceAny,
-        dest: IbGibSpaceAny,
-        identity: KeystoneIbGib_V1,
+        peer: SyncPeerWitness,
+        localSpace: IbGibSpaceAny,
+        metaspace: MetaspaceService,
+        primaryIdentity: KeystoneIbGib_V1,
+        primaryIdentitySecret: string,
         domainIbGibs: IbGib_V1[],
-        identitySecret?: string,
-    }): Promise<void> {
+    }): Promise<SyncSagaInfo> {
         const lc = `${this.lc}[${this.sync.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting...`); }
-
-            // 1. Generate UUID for this saga
-            // const uuid = await Factory_V1.primitive({ ib: "genuuid" }); // Hacky usage of primitive helper if available, or just UUID lib
-
-            // if we don't have a uuid, we can generate one here.
-            // but usually this is passed in.
-            // atow we are just generating one.
-            const uuid = await getUUID();
-
-            // ---------------------------------------------------------
-            // 1. Graph Generation & Classification
-            // ---------------------------------------------------------
-            // We want a live dependency graph to ensure we get the latest
-            // states of timelines.
-            const graph = await getDependencyGraph({
-                ibGibs: domainIbGibs,
-                live: true,
-                space: source,
-            });
-            const validGraph = graph && Object.keys(graph).length > 0;
-            if (logalot) { console.log(`${lc} graph generated. nodes: ${validGraph ? Object.keys(graph).length : 0}`); }
-
-            // 2. Classification
-            // We differentiate between "Stones" (Immutable, no timeline) and "Living" (Timelines).
-            // Stones can be synced in bulk without ordering.
-            // Living ibGibs must be grouped by timeline and ordered.
-            const ibGibs = validGraph ? Object.values(graph) : [];
-            const { mapWithTjp_YesDna, mapWithTjp_NoDna, mapWithoutTjps } = splitPerTjpAndOrDna({ ibGibs });
-
-            // "Stones" come from mapWithoutTjps
-            const stones = Object.values(mapWithoutTjps);
-
-            // "Living" come from both TJP maps
-            // We combine them to group by TJP
-            const living = [...Object.values(mapWithTjp_YesDna), ...Object.values(mapWithTjp_NoDna)];
-
-            if (logalot) {
-                console.log(`${lc} classification results (count):`);
-                console.log(`stones: ${stones.length}`);
-                console.log(`living: ${living.length}`);
+        if (logalot) { console.log(`${lc} starting...`); }
+
+        // 1. SETUP SAGA METADATA
+        const sagaId = await getUUID();
+
+        // Setup Observable & Promise
+        const updates$ = new Subject_V1<SyncSagaContextIbGib_V1>();
+        let resolveDone!: () => void;
+        let rejectDone!: (err: any) => void;
+        const done = new Promise<void>((resolve, reject) => {
+            resolveDone = resolve;
+            rejectDone = reject;
+        });
+
+        // WORKING CONTEXT (Transactional)
+        const tempSpace = await metaspace.createNewLocalSpace({
+            opts: {
+                allowCancel: false,
+                spaceName: undefined,
+                getFnPrompt: metaspace.getFnPrompt!,
+                logalot
             }
+        });
+        if (!tempSpace) { throw new Error(`Failed to create temp space (E: 8f4e2f3d6c1b4b1a8f4e2f3d6c1b4b1a)`); }
 
-            // 3. Timeline Ordering
-            // Group living ibGibs by TJP to identify distinct timelines.
-            // The helper returns them sorted by 'n' ascending.
-            const timelinesMap = getTimelinesGroupedByTjp({ ibGibs: living });
-
-            // todo: perform topological sort on timelinesMap based on inter-timeline references.
-            // For now, we sync independent timelines.
-
-            const payloadAddrs: string[] = [];
-            payloadAddrs.push(...stones.map(x => getIbGibAddr({ ibGib: x })));
-            // 3. Timeline Ordering (Topological Sort)
-            // Living ibGibs are grouped by timeline (TJP).
-            // We need to order these timelines based on dependencies.
-            const sortedTjps = this.sortTimelinesTopologically(timelinesMap);
-
-            // Add ordered timelines to payload
-            sortedTjps.forEach(tjp => {
-                const timeline = timelinesMap[tjp];
-                payloadAddrs.push(...timeline.map(x => getIbGibAddr({ ibGib: x })));
-            });
+        const cleanup = async () => {
+            // In-memory temp space cleanup if needed (e.g. if we used a specialized disposable space)
+            // await tempSpace.destroy();
+        };
 
-            // 2. INIT & Phase 2: Knowledge Exchange
-            const srcKnowledgeVector: { [tjp: string]: string } = {};
-            Object.keys(timelinesMap).forEach(tjp => {
-                const timeline = timelinesMap[tjp];
-                const tip = timeline[timeline.length - 1];
-                srcKnowledgeVector[tjp] = getIbGibAddr({ ibGib: tip });
-            });
+        // Async execution wrapper
+        (async () => {
+            try {
+                // 2. BOOTSTRAP IDENTITY (Session Keystone)
+                const config: any = {
+                    id: 'default',
+                    type: 'hash-reveal-v1',
+                    salt: sagaId,
+                    behavior: { size: 10, replenish: 'top-up', selectSequentially: 1, selectRandomly: 1, targetBindingChars: 0 },
+                    algo: 'SHA-256', rounds: 1
+                };
+                const sessionIdentity = await this.keystone.genesis({
+                    masterSecret: sagaId,
+                    configs: [config],
+                    metaspace,
+                    space: tempSpace
+                });
 
-            const initData: SyncInitData = {
-                knowledgeVector: srcKnowledgeVector,
-                identity: identity,
-                mode: 'push'
-            };
+                // 3. CREATE INITIAL FRAME (Stage.init)
+                const { sagaFrame: initFrame, srcGraph } = await this.createInitFrame({
+                    sagaId,
+                    sessionIdentity,
+                    localSpace,
+                    domainIbGibs,
+                    tempSpace,
+                    metaspace,
+                });
 
-            // Get Source Knowledge (Time -> Latest)
-            const srcTjps = Object.keys(timelinesMap);
-            // Get Dest Knowledge
-            const destKnowledge = await this.getLatestAddrsFromSpace({ space: dest, tjpAddrs: srcTjps });
-
-            const conflicts: string[] = [];
-            for (const tjp of srcTjps) {
-                const srcTimeline = timelinesMap[tjp];
-                const srcTip = srcTimeline[srcTimeline.length - 1];
-                const srcTipAddr = getIbGibAddr({ ibGib: srcTip });
-                const destTipAddr = destKnowledge[tjp];
-
-                if (destTipAddr && destTipAddr !== srcTipAddr) {
-                    // Divergence found. Check if Source knows Dest's tip.
-                    if (graph[destTipAddr]) {
-                        // Fast-Forward: Dest tip IS in our graph, so we are ahead.
-                        // No action needed, proceed to push.
-                    } else {
-                        // Conflict: Dest has a tip we don't know about.
-                        conflicts.push(tjp);
-                    }
+                // 4. EXECUTE SAGA LOOP (FSM)
+                const syncedIbGibs = await this.executeSagaLoop({
+                    initialFrame: initFrame,
+                    srcGraph,
+                    peer,
+                    sessionIdentity,
+                    updates$,
+                    tempSpace,
+                    metaspace
+                });
+
+                // 5. MERGE RESULT (Optimistic Commit)
+                if (syncedIbGibs && syncedIbGibs.length > 0) {
+                    if (logalot) { console.log(`${lc} Merging ${syncedIbGibs.length} synced ibGibs to localSpace...`); }
+                    await putInSpace({ space: localSpace, ibGibs: syncedIbGibs });
                 }
+
+                resolveDone();
+                updates$.complete();
+
+            } catch (error) {
+                console.error(`${lc} ${extractErrorMsg(error)}`);
+                rejectDone(error);
+                updates$.error(error);
+            } finally {
+                await cleanup();
             }
+        })();
 
-            // Lock conflicts
-            for (const tjp of conflicts) {
-                if (logalot) { console.log(`${lc} Conflict detected for TJP ${tjp}. Acquiring lock...`); }
-                // Lock VALIDITY: 60 seconds?
-                await lockSpace({
-                    space: dest,
-                    scope: tjp,
-                    secondsValid: 60,
-                    instanceId: uuid,
-                });
+        return {
+            sagaId,
+            updates$,
+            done
+        };
+    }
 
-                // todo: Implement Pull & Merge here
-                // 1. Pull delta from Dest (destTip -> ... -> common ancestor)
-                // 2. Merge locally
-                // 3. Update graph/timelinesMap with merged result
+    /**
+     * Drives the FSM loop of the Saga.
+     * Use "Ping Pong" style: Send Request -> Wait Response -> React (Handle) -> Repeat.
+     */
+    protected async executeSagaLoop({
+        initialFrame,
+        srcGraph,
+        peer,
+        sessionIdentity,
+        updates$,
+        tempSpace,
+        metaspace
+    }: {
+        initialFrame: SyncIbGib_V1,
+        srcGraph: { [addr: string]: IbGib_V1 },
+        peer: SyncPeerWitness,
+        sessionIdentity: KeystoneIbGib_V1,
+        updates$: Subject_V1<SyncSagaContextIbGib_V1>,
+        tempSpace: IbGibSpaceAny,
+        metaspace: MetaspaceService
+    }): Promise<IbGib_V1[]> {
+        const lc = `${this.lc}[${this.executeSagaLoop.name}]`;
+
+        let currentFrame: SyncIbGib_V1 | null = initialFrame;
+        let nextPayload: IbGib_V1[] = [];
+        const allReceivedIbGibs: IbGib_V1[] = [];
+
+        while (currentFrame) {
+            // A. Create Context (Request)
+            const payloadAddrs = nextPayload.map(p => getIbGibAddr({ ibGib: p }));
+
+            const requestCtx = await createSyncSagaContext({
+                cmd: SyncSagaContextCmd.process,
+                sagaFrame: currentFrame,
+                msgs: [],
+                sessionKeystones: [sessionIdentity],
+                payload: payloadAddrs.length > 0 ? payloadAddrs : undefined,
+            });
 
-                if (logalot) { console.warn(`${lc} Merge not fully implemented yet. Releasing lock.`); }
+            // B. Transmit
+            updates$.next(requestCtx);
+            const responseCtx = await peer.witness(requestCtx);
 
-                await unlockSpace({
-                    space: dest,
-                    scope: tjp,
-                    instanceId: uuid,
-                });
+            // C. Handle Response
+            if (!responseCtx) {
+                console.warn(`${lc} Peer returned no response context. Ending loop.`);
+                currentFrame = null;
+                break;
             }
 
-            const initFrame = await this.createSyncFrame({
-                uuid,
-                stage: SyncStage.init,
-                payload: initData,
-                identity
-            });
+            updates$.next(responseCtx);
 
-            // Persist Init to Dest (Handshake)
-            await putInSpace({ space: dest, ibGib: initFrame });
+            // D. Extract Remote Frame & React
+            const remoteFrameAddr = responseCtx.rel8ns?.sagaFrame?.[0];
+            if (!remoteFrameAddr) {
+                console.warn(`${lc} Peer response has no sagaFrame. Ending loop.`);
+                currentFrame = null;
+                break;
+            }
 
-            // 3. DELTA
-            // const payloadAddrs = [getIbGibAddr({ ibGib: identity })]; // Already computed above
+            const remoteFrame = await getFromSpace({ addr: remoteFrameAddr, space: tempSpace });
+            if (!remoteFrame) { throw new Error(`Could not resolve remote frame: ${remoteFrameAddr}`); }
 
-            const deltaData: SyncDeltaData = {
-                payloadAddrs
-            };
-            const deltaFrame = await this.createSyncFrame({
-                uuid,
-                stage: SyncStage.delta,
-                payload: deltaData,
-                identity
+            // React (Reducer)
+            const result = await this.handleSagaFrame({
+                sagaIbGib: remoteFrame as SyncIbGib_V1,
+                srcGraph,
+                space: tempSpace,
+                identity: sessionIdentity,
+                metaspace
             });
-            await putInSpace({ space: dest, ibGib: deltaFrame });
-
-            // 3.1 Stream the actual data (Batch Stream)
-            // We must preserve the order in payloadAddrs to respect dependencies.
-            // We batch them to improve throughput.
-            const BATCH_SIZE = 20;
-            for (let i = 0; i < payloadAddrs.length; i += BATCH_SIZE) {
-                const chunkAddrs = payloadAddrs.slice(i, i + BATCH_SIZE);
-                const chunkIbGibs = chunkAddrs
-                    .map(addr => {
-                        const ibGib = graph[addr];
-                        if (!ibGib) { throw new Error(`(UNEXPECTED) addr not found in graph: ${addr} (E: 8a402324057849318625aa85721665a5)`); }
-                        return ibGib;
-                    })
-                    .filter(ibGib => !isPrimitive({ ibGib }));
-
-                if (chunkIbGibs.length > 0) {
-                    if (logalot) { console.log(`${lc} streaming batch ${Math.ceil(i / BATCH_SIZE) + 1} (${chunkIbGibs.length} ibGibs)...`); }
-                    // We don't set isDna: true here because the batch might contain mixed types.
-                    // The Space implementation should handle routing based on internal metadata if needed.
-                    await putInSpace({ space: dest, ibGibs: chunkIbGibs });
-                }
+
+            currentFrame = result?.frame || null;
+            nextPayload = result?.payload || [];
+            if (result?.receivedPayload) {
+                allReceivedIbGibs.push(...result.receivedPayload);
             }
+        }
 
-            // 4. COMMIT
-            const commitData: SyncCommitData = {
-                success: true
-            };
-            const commitFrame = await this.createSyncFrame({
-                uuid,
-                stage: SyncStage.commit,
-                payload: commitData,
-                identity
-            });
-            await putInSpace({ space: dest, ibGib: commitFrame });
+        return allReceivedIbGibs;
+    }
+
+    protected async analyzeTimelines({
+        domainIbGibs,
+        space,
+    }: {
+        domainIbGibs: IbGib_V1[],
+        space: IbGibSpaceAny,
+    }): Promise<{
+        srcStones: IbGib_V1[],
+        srcTimelinesMap: { [tjp: string]: IbGib_V1[] },
+        srcSortedTjps: string[],
+        srcGraph: { [addr: string]: IbGib_V1 },
+    }> {
+        const lc = `${this.lc}[${this.analyzeTimelines.name}]`;
+        const srcGraph = await getDependencyGraph({
+            ibGibs: domainIbGibs,
+            live: true,
+            space,
+        });
+
+        const srcGraphIsValid = srcGraph && Object.keys(srcGraph).length > 0;
+        if (logalot) { console.log(`${lc} graph generated. nodes: ${srcGraphIsValid ? Object.keys(srcGraph).length : 0}`); }
+
+        const srcIbGibs = srcGraphIsValid ? Object.values(srcGraph) : [];
+        const {
+            mapWithTjp_YesDna: srcMapWithTjp_YesDna,
+            mapWithTjp_NoDna: srcMapWithTjp_NoDna,
+            mapWithoutTjps: src_MapWithoutTjps
+        } = splitPerTjpAndOrDna({ ibGibs: srcIbGibs });
+
+        const srcStones = Object.values(src_MapWithoutTjps);
+        const srcLiving = [...Object.values(srcMapWithTjp_YesDna), ...Object.values(srcMapWithTjp_NoDna)];
 
+        const srcTimelinesMap = getTimelinesGroupedByTjp({ ibGibs: srcLiving });
+        const srcSortedTjps = this.sortTimelinesTopologically(srcTimelinesMap);
+
+        return { srcStones, srcTimelinesMap, srcSortedTjps, srcGraph };
+    }
+
+    protected async resolveConflicts(): Promise<void> {
+        throw new Error("resolveConflicts is no longer supported.");
+    }
+
+    protected async processBatchStream(): Promise<void> {
+        // Deprecated by payload in SyncSagaContext
+        throw new Error("processBatchStream is no longer supported.");
+    }
+
+    /**
+     * Creates the Initial Saga Frame (Init Stage).
+     */
+    protected async createInitFrame({
+        sagaId,
+        sessionIdentity,
+        localSpace,
+        domainIbGibs,
+        tempSpace,
+        metaspace
+    }: {
+        sagaId: string,
+        sessionIdentity: KeystoneIbGib_V1,
+        localSpace: IbGibSpaceAny,
+        domainIbGibs: IbGib_V1[],
+        tempSpace: IbGibSpaceAny,
+        metaspace: MetaspaceService
+    }): Promise<{ sagaFrame: SyncIbGib_V1, srcGraph: { [addr: string]: IbGib_V1 } }> {
+        const initData: SyncSagaMessageInitData_V1 = {
+            sagaId,
+            stage: SyncStage.init,
+            knowledgeVector: {},
+            identity: sessionIdentity, // KeystoneIbGib is already public data
+            mode: SyncMode.sync,
+        };
+
+        // Populate Knowledge Vector
+        const { srcTimelinesMap, srcGraph } = await this.analyzeTimelines({ domainIbGibs, space: localSpace });
+        Object.keys(srcTimelinesMap).forEach(tjp => {
+            const timeline = srcTimelinesMap[tjp];
+            const tip = timeline.at(-1)!;
+            initData.knowledgeVector[tjp] = getIbGibAddr({ ibGib: tip });
+        });
+
+        const initStone = await this.createSyncMsgStone({
+            data: initData,
+            space: tempSpace,
+            metaspace
+        });
+
+        const sagaFrame = await this.evolveSyncSagaIbGib({
+            msgStones: [initStone],
+            identity: sessionIdentity,
+            space: tempSpace,
+            metaspace
+        });
+
+        return { sagaFrame, srcGraph };
+    }
+
+    /**
+     * Reacts to an incoming saga frame and dispatches to appropriate handler.
+     */
+    async handleSagaFrame({
+        sagaIbGib,
+        srcGraph,
+        space,
+        identity,
+        identitySecret,
+        metaspace,
+    }: {
+        sagaIbGib: SyncIbGib_V1,
+        srcGraph: { [addr: string]: IbGib_V1 },
+        space: IbGibSpaceAny,
+        identity: KeystoneIbGib_V1,
+        identitySecret?: string,
+        metaspace: MetaspaceService,
+    }): Promise<{ frame: SyncIbGib_V1, payload?: IbGib_V1[], receivedPayload?: IbGib_V1[] } | null> {
+        const lc = `${this.lc}[${this.handleSagaFrame.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 5deec8a1f7a6d263c88cd458ad990826)`); }
+
+            if (!sagaIbGib.data) { throw new Error(`(UNEXPECTED) sagaIbGib.data falsy? (E: 71b938adf1d87c2527bfd4f86dfd0826)`); }
+            if (logalot) { console.log(`${lc} handling frame stage: ${sagaIbGib.data.stage}`); }
+
+            // Get Stage from Stone (or Frame for Init fallback)
+            const { stage, payload } = await this.getStageAndPayloadFromFrame({ ibGib: sagaIbGib, space });
+
+            switch (stage) {
+                case SyncStage.init:
+                    return await this.handleInitFrame({ sagaIbGib, payload, space, metaspace, identity, identitySecret });
+
+                case SyncStage.ack:
+                    return await this.handleAckFrame({ sagaIbGib, srcGraph, space, metaspace, identity });
+
+                case SyncStage.delta:
+                    return await this.handleDeltaFrame({ sagaIbGib, srcGraph, space, identity, metaspace });
+
+                case SyncStage.commit:
+                    return await this.handleCommitFrame({ sagaIbGib, space });
+
+                default:
+                    throw new Error(`${lc} (UNEXPECTED) Unknown sync stage: ${stage} (E: 9c2b4c8a6d34469f8263544710183355)`);
+            }
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;
@@ -325,93 +399,451 @@ export class SyncSagaCoordinator {
         }
     }
 
-    protected async createSyncFrame({
-        uuid,
-        stage,
+    // #region Handlers
+
+    protected async handleInitFrame({
+        sagaIbGib,
         payload,
-        identity
+        space,
+        metaspace,
+        identity,
+        identitySecret,
     }: {
-        uuid: string,
-        stage: any, // SyncStage
+        sagaIbGib: SyncIbGib_V1,
         payload: any,
-        identity: KeystoneIbGib_V1
-    }): Promise<SyncIbGib_V1> {
-        const data: SyncData_V1 = {
-            uuid,
-            stage,
-            payload
+        space: IbGibSpaceAny,
+        metaspace: MetaspaceService,
+        identity: KeystoneIbGib_V1,
+        identitySecret?: string,
+    }): Promise<{ frame: SyncIbGib_V1, payload?: IbGib_V1[] } | null> {
+        const lc = `${this.lc}[${this.handleInitFrame.name}]`;
+        if (logalot) { console.log(`${lc} starting...`); }
+
+        // Extract Init Data
+        const initData = sagaIbGib.data!.payload as SyncInitData;
+        if (!initData || !initData.knowledgeVector) {
+            throw new Error(`${lc} Invalid init frame: missing knowledgeVector (E: ed02c869e028d2d06841b9c7f80f2826)`);
+        }
+        const remoteKV = initData.knowledgeVector;
+        const remoteTjps = Object.keys(remoteKV);
+
+        // 1. Get Local Latest Addrs for all TJPs
+        let localKV: { [tjp: string]: string | null } = {};
+        if (remoteTjps.length > 0) {
+            // Batch get latest addrs for the TJPs
+            const arg = await space.argy({
+                argData: {
+                    cmd: 'get',
+                    cmdModifiers: ['latest', 'tjps'], // interprets input addrs as TJPs
+                    ibGibAddrs: remoteTjps,
+                } as any
+            });
+            const res = await space.witness(arg);
+            if (res?.data?.latestAddrsMap) {
+                localKV = res.data.latestAddrsMap;
+            }
+        }
+
+        // 2. Gap Analysis
+        const deltaReqAddrs: string[] = [];
+        const pushOfferAddrs: string[] = [];
+        // const divergentTjps: string[] = []; // Handle later
+
+        for (const tjp of remoteTjps) {
+            const remoteAddr = remoteKV[tjp];
+            const localAddr = localKV[tjp];
+
+            if (!localAddr) {
+                deltaReqAddrs.push(remoteAddr);
+                continue;
+            }
+
+            if (localAddr === remoteAddr) {
+                continue;
+            }
+
+            // Check if Remote is in Local's PAST (Local is Ahead -> Push Offer)
+            const isRemoteInPast = await isPastFrame({
+                olderAddr: remoteAddr,
+                newerAddr: localAddr,
+                space,
+            });
+
+            if (isRemoteInPast) {
+                pushOfferAddrs.push(localAddr);
+            } else {
+                deltaReqAddrs.push(remoteAddr);
+            }
+        }
+
+        // 3. Create Ack Frame
+        const sagaId = sagaIbGib.data!.uuid;
+        // Create Payload Stone
+        const ackData: SyncSagaMessageAckData_V1 = {
+            sagaId,
+            stage: SyncStage.ack,
+            deltaReqAddrs,
+            pushOfferAddrs,
         };
-        const ib = await getSyncIb({ data });
-        // Create the ibGib using Factory? Or manually?
-        // Factory_V1.firstGen usually.
-        const res = await Factory_V1.firstGen({
-            parentIbGib: Factory_V1.primitive({ ib: SYNC_ATOM }),
-            ib,
-            data,
-            rel8ns: {
-                identity: [getIbGibAddr({ ibGib: identity })]
-            },
-            /**
-             * dna is used for merging dynamic timelines, a la a CRDT-like
-             * mechanism that looks somewhat like event sourcing but using
-             * crypto primitives. in our particular case, the sync should be a
-             * single, one-off timeline (not to be used for any future merging),
-             * so we don't need dna.
-             */
-            dna: false,
-            tjp: {
-                timestamp: true,
-                /**
-                 * we'll use the uuid passed in
-                 */
-                uuid: false
-            },
-            nCounter: true,
+
+        const ackStone = await this.createSyncMsgStone({
+            data: ackData,
+            space,
+            metaspace,
+        });
+
+        // Evolve Saga
+        const ackFrame = await this.evolveSyncSagaIbGib({
+            prevSagaIbGib: sagaIbGib,
+            msgStones: [ackStone],
+            identity,
+            space,
+            metaspace,
         });
-        return res.newIbGib as SyncIbGib_V1;
+
+        return { frame: ackFrame };
     }
 
-    protected async getLatestAddrsFromSpace({
+    protected async handleAckFrame({
+        sagaIbGib,
+        srcGraph,
         space,
-        tjpAddrs,
+        metaspace,
+        identity,
     }: {
+        sagaIbGib: SyncIbGib_V1,
+        srcGraph: { [addr: string]: IbGib_V1 },
         space: IbGibSpaceAny,
-        tjpAddrs: string[],
-    }): Promise<{ [tjpAddr: string]: string }> {
-        const lc = `${this.lc}[${this.getLatestAddrsFromSpace.name}]`;
-        try {
-            if (tjpAddrs.length === 0) { return {}; }
+        metaspace: MetaspaceService,
+        identity: KeystoneIbGib_V1,
+    }): Promise<{ frame: SyncIbGib_V1, payload?: IbGib_V1[] } | null> {
+        const lc = `${this.lc}[${this.handleAckFrame.name}]`;
+        if (logalot) { console.log(`${lc} starting...`); }
 
-            // Using the space's witness/argy pattern to invoke 'get' with 'latest' modifier
-            const arg = await space.argy({
-                ibMetadata: getSpaceArgMetadata({ space }),
-                argData: {
+        const { payload } = await this.getStageAndPayloadFromFrame({ ibGib: sagaIbGib, space });
+        const ackData = payload as SyncSagaMessageAckData_V1;
+
+        if (!ackData || ackData.stage !== SyncStage.ack) {
+            throw new Error(`${lc} Invalid ack frame (E: 2e8b0a94b5954a66a6a1a7a0b3f5b7a1)`);
+        }
+
+        const deltaReqAddrs = ackData.deltaReqAddrs || [];
+        const pushOfferAddrs = ackData.pushOfferAddrs || [];
+
+        // 1. Process Push Offers (Pull Requests) (Naive: Accept all if missing)
+        const pullReqAddrs: string[] = [];
+        for (const addr of pushOfferAddrs) {
+            const existing = srcGraph[addr] || (await getFromSpace({ addr, space })).ibGibs?.[0];
+            if (!existing) {
+                pullReqAddrs.push(addr);
+            }
+        }
+
+        // 2. Process Delta Requests (Push Payload)
+        const payloadIbGibs: IbGib_V1[] = [];
+        for (const addr of deltaReqAddrs) {
+            let ibGib = srcGraph[addr];
+            if (!ibGib) {
+                const res = await getFromSpace({ addr, space });
+                if (res.ibGibs && res.ibGibs.length > 0) {
+                    ibGib = res.ibGibs[0];
+                }
+            }
+            if (ibGib) {
+                payloadIbGibs.push(ibGib);
+            } else {
+                console.warn(`${lc} Requested addr not found: ${addr}`);
+            }
+        }
+
+        // 3. Create Delta Frame
+        const sagaId = ackData.sagaId;
+        const deltaData: SyncSagaMessageDeltaData_V1 = {
+            sagaId,
+            stage: SyncStage.delta,
+            payloadAddrs: payloadIbGibs.map(p => getIbGibAddr({ ibGib: p })),
+            requests: pullReqAddrs.length > 0 ? pullReqAddrs : undefined,
+        };
+
+        const deltaStone = await this.createSyncMsgStone({
+            data: deltaData,
+            space,
+            metaspace,
+        });
+
+        const deltaFrame = await this.evolveSyncSagaIbGib({
+            prevSagaIbGib: sagaIbGib,
+            msgStones: [deltaStone],
+            identity,
+            space,
+            metaspace,
+        });
+
+        return { frame: deltaFrame, payload: payloadIbGibs };
+    }
+
+    protected async handleDeltaFrame({
+        sagaIbGib,
+        srcGraph,
+        space,
+        metaspace,
+        identity,
+    }: {
+        sagaIbGib: SyncIbGib_V1,
+        srcGraph: { [addr: string]: IbGib_V1 },
+        space: IbGibSpaceAny,
+        metaspace: MetaspaceService,
+        identity: KeystoneIbGib_V1,
+    }): Promise<{ frame: SyncIbGib_V1, payload?: IbGib_V1[], receivedPayload?: IbGib_V1[] } | null> {
+        const lc = `${this.lc}[${this.handleDeltaFrame.name}]`;
+        if (logalot) { console.log(`${lc} starting...`); }
+
+        const { payload } = await this.getStageAndPayloadFromFrame({ ibGib: sagaIbGib, space });
+        const deltaData = payload as SyncSagaMessageDeltaData_V1;
+
+        if (!deltaData || deltaData.stage !== SyncStage.delta) {
+            throw new Error(`${lc} Invalid delta frame (E: 7c28c8d8f08a4421b8344e6727271421)`);
+        }
+
+        const payloadAddrs = deltaData.payloadAddrs || [];
+        const requests = deltaData.requests || [];
+
+        // 1. Process Received Payload
+        const receivedPayload: IbGib_V1[] = [];
+        if (payloadAddrs.length > 0) {
+            const res = await space.witness({
+                attribute: 'ibGibs',
+                arg: {
+                    ibGibAddrs: payloadAddrs,
                     cmd: 'get',
-                    cmdModifiers: ['latest', 'addrs'],
-                    ibGibAddrs: tjpAddrs,
+                } as any
+            });
+            if (res.data?.ibGibs) {
+                receivedPayload.push(...res.data.ibGibs);
+            }
+        }
+
+        // 2. Fulfill Requests (Outgoing Payload)
+        const outgoingPayload: IbGib_V1[] = [];
+        for (const addr of requests) {
+            let ibGib = srcGraph[addr];
+            if (!ibGib) {
+                const res = await getFromSpace({ addr, space });
+                if (res.ibGibs && res.ibGibs.length > 0) {
+                    ibGib = res.ibGibs[0];
                 }
+            }
+            if (ibGib) {
+                outgoingPayload.push(ibGib);
+            }
+        }
+
+        // 3. Determine Next Stage
+        if (requests.length > 0) {
+            // They requested more data -> Send Delta
+            const sagaId = deltaData.sagaId;
+            const responseDeltaData: SyncSagaMessageDeltaData_V1 = {
+                sagaId,
+                stage: SyncStage.delta,
+                payloadAddrs: outgoingPayload.map(p => getIbGibAddr({ ibGib: p })),
+            };
+
+            const deltaStone = await this.createSyncMsgStone({
+                data: responseDeltaData,
+                space,
+                metaspace
             });
-            const result = await space.witness(arg);
-
-            const map: { [tjp: string]: string } = {};
-            if (result?.data?.success && result.data.addrs) {
-                // assume 1-to-1 mapping order as per convention if successful
-                // verification is hard without specific return map
-                if (result.data.addrs.length === tjpAddrs.length) {
-                    for (let i = 0; i < tjpAddrs.length; i++) {
-                        map[tjpAddrs[i]] = result.data.addrs[i];
-                    }
-                } else {
-                    console.warn(`${lc} result addrs length mismatch. requested: ${tjpAddrs.length}, got: ${result.data.addrs.length}. Mapping might be unsafe.`);
+
+            const deltaFrame = await this.evolveSyncSagaIbGib({
+                prevSagaIbGib: sagaIbGib,
+                msgStones: [deltaStone],
+                identity,
+                space,
+                metaspace
+            });
+
+            return { frame: deltaFrame, payload: outgoingPayload, receivedPayload };
+
+        } else {
+            // No requests -> Commit
+            const sagaId = deltaData.sagaId;
+            const commitData: SyncSagaMessageCommitData_V1 = {
+                sagaId,
+                stage: SyncStage.commit,
+                success: true,
+            };
+
+            const commitStone = await this.createSyncMsgStone({
+                data: commitData,
+                space,
+                metaspace
+            });
+
+            const commitFrame = await this.evolveSyncSagaIbGib({
+                prevSagaIbGib: sagaIbGib,
+                msgStones: [commitStone],
+                identity,
+                space,
+                metaspace
+            });
+
+            return { frame: commitFrame, receivedPayload };
+        }
+    }
+
+    protected async handleCommitFrame({
+        sagaIbGib,
+        space,
+    }: {
+        sagaIbGib: SyncIbGib_V1,
+        space: IbGibSpaceAny,
+    }): Promise<{ frame: SyncIbGib_V1, payload?: IbGib_V1[] } | null> {
+        const lc = `${this.lc}[${this.handleCommitFrame.name}]`;
+        if (logalot) { console.log(`${lc} Commit received. Saga complete.`); }
+        return null;
+    }
+
+    // #endregion Handlers
+
+    protected async createSyncMsgStone<TStoneData extends SyncSagaMessageData_V1>({
+        data,
+        space,
+        metaspace,
+    }: {
+        data: TStoneData,
+        space: IbGibSpaceAny,
+        metaspace: MetaspaceService,
+    }): Promise<IbGib_V1<TStoneData>> {
+        const ib = await getSyncSagaMessageIb({ data });
+        const stone = await Factory_V1.stone({
+            ib,
+            parentPrimitiveIb: SYNC_SAGA_MSG_ATOM,
+            data,
+            uuid: true, // we want the stone to have its own uniqueness
+        });
+        await putInSpace({ space, ibGib: stone });
+        await metaspace.registerNewIbGib({ ibGib: stone });
+        return stone as IbGib_V1<TStoneData>;
+    }
+
+
+    /**
+     * Evolves the saga timeline with a new frame.
+     */
+    protected async evolveSyncSagaIbGib({
+        prevSagaIbGib,
+        msgStones,
+        identity,
+        space,
+        metaspace,
+    }: {
+        prevSagaIbGib?: SyncIbGib_V1,
+        msgStones: IbGib_V1[],
+        identity: KeystoneIbGib_V1,
+        space: IbGibSpaceAny,
+        metaspace: MetaspaceService,
+    }): Promise<SyncIbGib_V1> {
+        const lc = `${this.lc}[${this.evolveSyncSagaIbGib.name}]`;
+        try {
+            // Validation
+            if (!msgStones || msgStones.length === 0) {
+                throw new Error(`${lc} msgStones required (E: d13f8afcfb8816aeb26baae7df3ef726)`);
+            }
+            const firstStoneData = msgStones[0].data as SyncSagaMessageData_V1;
+            if (!firstStoneData?.sagaId || !firstStoneData?.stage) {
+                throw new Error(`${lc} Invalid stone data (missing sagaId or stage) (E: c004f85ce8f8958b11839f8d68c38826)`);
+            }
+            const sagaId = firstStoneData.sagaId;
+            const stage = firstStoneData.stage;
+
+            // Ensure all stones match sagaId and stage
+            for (const stone of msgStones) {
+                const d = stone.data as SyncSagaMessageData_V1;
+                if (d.sagaId !== sagaId) {
+                    throw new Error(`${lc} Mismatched sagaId in stones. Expected ${sagaId}, got ${d.sagaId} (E: 29e02719e426ecbbf8ee66887a2be226)`);
+                }
+                if (d.stage !== stage) {
+                    throw new Error(`${lc} Mismatched stage in stones. Expected ${stage}, got ${d.stage} (E: d12c6571b0882f762921b60880c3f826)`);
                 }
             }
-            return map;
+
+            const identityAddr = getIbGibAddr({ ibGib: identity });
+
+            if (prevSagaIbGib) {
+                // Append to existing timeline
+                const resAppend = await appendToTimeline({
+                    timeline: prevSagaIbGib,
+                    rel8nInfos: [
+                        {
+                            rel8nName: SYNC_MSG_REL8N_NAME,
+                            ibGibs: msgStones,
+                        },
+                        {
+                            rel8nName: 'identity',
+                            ibGibs: [identity],
+                        }
+                    ],
+                    metaspace,
+                    space,
+                    noDna: true, // Explicitly no DNA for sync frames
+                });
+
+                const newFrame = resAppend as SyncIbGib_V1;
+                return newFrame;
+            } else {
+                // Create New Timeline (Root Frame)
+                const data: SyncData_V1 = {
+                    uuid: sagaId,
+                    stage,
+                    payload: undefined, // Data in stone
+                };
+                const ib = await getSyncIb({ data });
+
+                const stoneAddrs = msgStones.map(s => getIbGibAddr({ ibGib: s }));
+
+                const resNew = await createTimeline({
+                    space,
+                    metaspace,
+                    ib,
+                    data,
+                    rel8ns: {
+                        [SYNC_MSG_REL8N_NAME]: stoneAddrs,
+                        identity: [identityAddr],
+                    },
+                    parentIb: SYNC_ATOM, // "sync"
+                    noDna: true,
+                });
+
+                return resNew.newIbGib as SyncIbGib_V1;
+            }
+
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
-            return {}; // fail safe
+            throw error;
         }
     }
 
+    protected async getStageAndPayloadFromFrame({ ibGib, space }: { ibGib: IbGib_V1, space: IbGibSpaceAny }): Promise<{ stage: SyncStage, payload: any }> {
+        // 1. Try Stone (Primary)
+        const stoneAddrs = ibGib.rel8ns?.[SYNC_MSG_REL8N_NAME];
+        if (stoneAddrs && stoneAddrs.length > 0) {
+            const stoneAddr = stoneAddrs[0];
+            const res = await getFromSpace({ addr: stoneAddr, space });
+            if (res.ibGibs && res.ibGibs.length > 0) {
+                const stone = res.ibGibs[0];
+                if (stone.data && stone.data.stage) {
+                    return { stage: stone.data.stage, payload: stone.data };
+                }
+            }
+        }
+
+        // 2. Fallback to Frame Data (Legacy/Init compatibility)
+        if (ibGib.data && ibGib.data.stage) {
+            return { stage: ibGib.data.stage, payload: ibGib.data.payload };
+        }
+
+        throw new Error(`Could not determine stage from frame ${getIbGibAddr({ ibGib })}`);
+    }
     protected sortTimelinesTopologically(timelines: { [tjp: string]: IbGib_V1[] }): string[] {
         const lc = `${this.lc}[${this.sortTimelinesTopologically.name}]`;
         const tjps = Object.keys(timelines);
@@ -474,4 +906,5 @@ export class SyncSagaCoordinator {
 
         return sorted;
     }
+
 }