@ibgib/core-gib 0.1.22 → 0.1.23

package/src/sync/sync-helpers.mts

@@ -1,13 +1,15 @@
-import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { extractErrorMsg, getUUID } from "@ibgib/helper-gib/dist/helpers/utils-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_ATOM, SYNC_MSG_REL8N_NAME } from "./sync-constants.mjs";
-import { SyncData_V1, SyncIb_V1, SyncIbGib_V1 } from "./sync-types.mjs";
+import { isValidSyncConflictStrategy, SYNC_CONFLICT_STRATEGY_VALID_VALUES, SyncData_V1, SyncIb_V1, SyncIbGib_V1, SyncSagaFrameDependencyGraph } from "./sync-types.mjs";
 import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
 import { getFromSpace } from "../witness/space/space-helper.mjs";
 import { IbGibSpaceResultData, IbGibSpaceResultIbGib, IbGibSpaceResultRel8ns } from "../witness/space/space-types.mjs";
+import { KeystoneIbGib_V1 } from "../keystone/keystone-types.mjs";
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -69,94 +71,79 @@ export async function parseSyncIb({
 }
 
 /**
- * Checks if an address (`olderAddr`) is in the past frames of another (`newerAddr`).
+ * @returns the name for a tempSpace in the sync
+ */
+export async function getTempSpaceName(): Promise<string> {
+    const uuid = await getUUID();
+    return `tmp_sync_space_${uuid.substring(0, 8)}`;
+}
+
+/**
+ * UNTESTED
  * 
- * Efficiently uses `inMemoryGraph` if provided to avoid Space I/O.
- * Otherwise falls back to traversing using `space`.
+ * Checks if an {@link olderAddr} is the address of a past frame in the ibgib
+ * with {@link newerAddr}.
  */
 export async function isPastFrame({
     olderAddr,
     newerAddr,
     space,
-    inMemoryGraph,
 }: {
     olderAddr: string, // Was ancestorAddr
     newerAddr: string, // Was descendantAddr
-    space?: IbGibSpaceAny,
-    inMemoryGraph?: { [addr: string]: IbGib_V1 },
+    space: IbGibSpaceAny,
 }): Promise<boolean> {
-    if (olderAddr === newerAddr) return true;
-
-    // Quick check if optimization allowed
-    if (inMemoryGraph) {
-        // Optimization: Iterate the graph values (or keys) and see if olderAddr is in any 'past'
-        // Actually we need to traverse from newerAddr back to olderAddr using the graph.
-
-        const queue = [newerAddr];
-        const visited = new Set<string>();
-
-        while (queue.length > 0) {
-            const currentAddr = queue.shift()!;
-            if (visited.has(currentAddr)) continue;
-            visited.add(currentAddr);
-
-            if (currentAddr === olderAddr) return true;
-
-            const node = inMemoryGraph[currentAddr];
-            // If node not in memory graph, we can't traverse further in memory.
-            // If we have space, we could fallback, but usually mixed mode is tricky.
-            // For now, if provided inMemoryGraph, assume it contains the relevant segment.
-            if (!node && space) {
-                // optional fallback to space if allowed?
-                // User requirement: "at most we are looking... in dependency graph". 
-                // So let's fallback if space provided.
-                const res = await getFromSpace({ space, addr: currentAddr });
-                if (res.success && res.ibGibs?.length) {
-                    const spaceNode = res.ibGibs[0];
-                    if (spaceNode.rel8ns && spaceNode.rel8ns.past) {
-                        for (const pastAddr of spaceNode.rel8ns.past) {
-                            if (!visited.has(pastAddr)) queue.push(pastAddr);
-                        }
-                    }
-                }
-                continue;
-            } else if (!node) {
-                continue; // Dead end in memory
-            }
+    const lc = `[${isPastFrame.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 4b3548cbc9a2eb749f447ed82fdcf826)`); }
 
-            if (node.rel8ns && node.rel8ns.past) {
-                for (const pastAddr of node.rel8ns.past) {
-                    if (!visited.has(pastAddr)) queue.push(pastAddr);
-                }
-            }
+        // quick check...
+        if (olderAddr === newerAddr) {
+            return true; /* <<<< returns early */
         }
-        return false;
-    }
-
-    // Fallback to purely space-based traversal if no memory graph
-    if (!space) { throw new Error(`Must provide either space or inMemoryGraph for ancestry check.`); }
 
-    const queue = [newerAddr];
-    const visited = new Set<string>();
+        // diff, so get the actual ibGib
+        let newerIbGib: IbGib_V1;
+        const res = await getFromSpace({ space, addr: newerAddr });
+        if (res.success && res.ibGibs?.length === 1) {
+            newerIbGib = res.ibGibs[0];
+        } else {
+            throw new Error(`couldn't get newerAddr (${newerAddr}) from space (${space.ib}). (E: 36c758c22b181b2c89a1cd28937a6826)`);
+        }
 
-    while (queue.length > 0) {
-        const currentAddr = queue.shift()!;
-        if (visited.has(currentAddr)) continue;
-        visited.add(currentAddr);
+        if (!newerIbGib.rel8ns) {
+            console.warn(`${lc} newerIbGib.rel8ns falsy? newerAddr: ${newerAddr}. (W: 6f920811f7080281189f767813814826)`);
+            return false; /* <<<< returns early */
+        }
 
-        if (currentAddr === olderAddr) return true;
+        const pastAddrs = newerIbGib.rel8ns.past ?? [];
+        if (pastAddrs.length === 0) {
+            return false; /* <<<< returns early */
+        }
 
-        const res = await getFromSpace({ space, addr: currentAddr });
-        if (!res.success || !res.ibGibs || res.ibGibs.length === 0) continue;
-        const node = res.ibGibs[0];
-        if (node.rel8ns && node.rel8ns.past) {
-            for (const pastAddr of node.rel8ns.past) {
-                if (!visited.has(pastAddr)) queue.push(pastAddr);
-            }
+        if (pastAddrs.includes(olderAddr)) {
+            return true; /* <<<< returns early */
         }
+
+        // at this point, for most ibgibs we could leave it here. But
+        // conceivably, the past could be a linked rel8n. so recurse on the
+        // oldest in the past
+
+        const oldestAddrInThisPast = pastAddrs[0];
+        const resRecurse = await isPastFrame({
+            olderAddr,
+            newerAddr: oldestAddrInThisPast,
+            space,
+        });
+
+        return resRecurse;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
     }
 
-    return false;
 }
 
 /**
@@ -168,43 +155,128 @@ export async function isPastFrame({
  * It only retrieves the *content* of the current frame:
  * 1. The Frame itself.
  * 2. The Message Stone(s) (`rel8ns.msg`).
- * 3. The Identity (`rel8ns.identity`).
+ * 3. The Identity(s) (`rel8ns.identity`).
  * 
  * This is used for efficient transmission of the "Current Step" without re-sending the entire history.
  */
-export async function getSyncSagaDependencyGraph({
-    ibGib,
-    space,
+export async function getSyncSagaFrameDependencyGraph({
+    sagaIbGib,
+    localSpace,
 }: {
-    ibGib: IbGib_V1,
-    space: IbGibSpaceAny,
-}): Promise<IbGib_V1[]> {
-    const lc = `[${getSyncSagaDependencyGraph.name}]`;
-    const result: IbGib_V1[] = [ibGib];
+    sagaIbGib: SyncIbGib_V1,
+    localSpace: IbGibSpaceAny,
+}): Promise<SyncSagaFrameDependencyGraph> {
+    const lc = `[${getSyncSagaFrameDependencyGraph.name}]`;
 
     // Helper to fetch and push
-    const fetchAndPush = async (addrs: string[]) => {
-        const res = await getFromSpace({ space, addrs });
-        if (res.success && res.ibGibs?.length === addrs.length) {
-            res.ibGibs!.forEach(x => result.push(x));
+    const fnGet = async (addrs: string[]) => {
+        const resGet = await getFromSpace({ space: localSpace, addrs });
+        if (resGet.success && resGet.ibGibs?.length === addrs.length) {
+            return resGet.ibGibs!;
         } else {
             const resIbGib =
-                res.rawResultIbGib as IbGibSpaceResultIbGib<IbGib_V1, IbGibSpaceResultData, IbGibSpaceResultRel8ns>
-            if (!resIbGib.data) { throw new Error(`(UNEXPECTED) res.rawResultIbGib.data falsy? (E: c26c681d2f831fc537ba6f48fee36d26)`); }
+                resGet.rawResultIbGib as IbGibSpaceResultIbGib<IbGib_V1, IbGibSpaceResultData, IbGibSpaceResultRel8ns>
+            if (!resIbGib.data) { throw new Error(`(UNEXPECTED) resGet.rawResultIbGib.data falsy? (E: c26c681d2f831fc537ba6f48fee36d26)`); }
             throw new Error(`(UNEXPECTED) couldn't find addrs? addrsNotFound: ${resIbGib.data.addrsNotFound}? (E: 43b7b5a6ad982715c8f3eed69bfa0d26)`);
         }
     };
 
-    if (ibGib.rel8ns) {
-        // 1. Message Stones (Payload of the frame)
-        if (ibGib.rel8ns[SYNC_MSG_REL8N_NAME] && ibGib.rel8ns[SYNC_MSG_REL8N_NAME].length > 0) {
-            await fetchAndPush(ibGib.rel8ns[SYNC_MSG_REL8N_NAME]);
+    const validationErrors = await validateSyncSagaFrame({ sagaIbGib });
+    if (validationErrors.length > 0) {
+        throw new Error(`invalid sync sagaIbGib. validationErrors: ${validationErrors} (E: 19f9e8c9643858ff41312b62293d2126)`);
+    }
+
+    if (!sagaIbGib.rel8ns) { throw new Error(`(UNEXPECTED) validated sagaIbGib.rel8ns falsy? (E: 73af48be8bbf271ec5cf78187ce8c826)`); }
+
+    // msg stones
+    const msgStoneAddrs = sagaIbGib.rel8ns[SYNC_MSG_REL8N_NAME]!;
+    const msgStones = await fnGet(msgStoneAddrs);
+
+    // identities
+    const identities = sagaIbGib.rel8ns.identity && sagaIbGib.rel8ns.identity.length > 0 ?
+        await fnGet(sagaIbGib.rel8ns.identity) as KeystoneIbGib_V1[] :
+        [];
+
+    return { sagaIbGib, msgStones, identities, };
+}
+
+/**
+ * only validates this single frame. does not validate any dependencies or past.
+ * @returns array of errors, empty if valid
+ */
+export async function validateSyncSagaFrame({
+    sagaIbGib
+}: {
+    sagaIbGib: SyncIbGib_V1;
+}): Promise<string[]> {
+    const lc = `[${validateSyncSagaFrame.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: dac978e9ec5820f128fbbff817b82826)`); }
+
+        const errors: string[] = await validateIbGibIntrinsically({ ibGib: sagaIbGib }) ?? [];
+
+        // intrinsic errors are a non-starter
+        if (errors.length > 0) { return errors; /* <<<< returns early */ }
+
+        if (sagaIbGib.data) {
+            const { data } = sagaIbGib;
+
+            if (data.uuid) {
+                // todo: validate uuid
+            } else {
+                errors.push(`data.uuid required (E: aa24eeda7b88d22e5832a2e8083c0826)`);
+            }
+            if (data.timestamp) {
+                // todo: validate timestamp
+            } else {
+                errors.push(`data.timestamp required (E: 9c82a88548f4b63c38687428754b3826)`);
+            }
+            if (data.timestampMs || data.timestampMs === 0) {
+                // todo: validate timestampMs
+            } else {
+                errors.push(`data.timestampMs required (E: 9c82a88548f4b63c38687428754b3826)`);
+            }
+
+            if (data.conflictStrategy) {
+                if (!isValidSyncConflictStrategy(data.conflictStrategy)) {
+                    errors.push(`data.conflictStrategy (${data.conflictStrategy}) is invalid. Must be one of "${SYNC_CONFLICT_STRATEGY_VALID_VALUES}". (E: 6223a8813b688fa2c8644fa8a491bf26)`)
+                }
+            } else {
+                errors.push(`data.conflictStrategy required (E: 9c82a88548f4b63c38687428754b3826)`);
+            }
+
+            if (data.expirationTimestamp) {
+                // todo: validate expirationTimestamp
+            }
+
+            if (data.errors) {
+                // todo: validate errors?
+            }
+
+            if (data.successCount) {
+                // todo: validate successCount
+            }
+
+        } else {
+            errors.push(`sagaIbGib.data falsy (E: 4de5e8de589d0af7245600fb4fe30926)`);
         }
-        // 2. Identity (Signer)
-        if (ibGib.rel8ns.identity && ibGib.rel8ns.identity.length > 0) {
-            await fetchAndPush(ibGib.rel8ns.identity);
+
+        if (sagaIbGib.rel8ns) {
+            const msgAddrs = sagaIbGib.rel8ns[SYNC_MSG_REL8N_NAME];
+            if (msgAddrs && msgAddrs.length > 0) {
+                // todo: validate the syncmsg addr?
+            } else {
+                errors.push(`sagaIbGib.rel8ns[SYNC_MSG_REL8N_NAME] required. (E: df648dc18148e718682acb4842ecf826)`);
+            }
+        } else {
+            errors.push(`sagaIbGib.rel8ns falsy (E: da37aa492a7275b68a5e1912c7a5e126)`);
         }
-    }
 
-    return result;
+        return errors;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
 }

package/src/sync/sync-innerspace-constants.respec.mts

@@ -69,16 +69,17 @@ await respecfully(sir, `Sync Constants (No TJP)`, async () => {
         const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
         const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
 
-        const peer = new SyncPeerInnerspace_V1({
-            senderSpace: sourceSpace,
-            receiverSpace: destSpace,
-            receiverCoordinator: receiverCoordinator,
-            receiverMetaspace: metaspace,
-            receiverTempSpace: 0 as any, // placeholder this is wrong
-            senderTempSpace: 0 as any, // placeholder this is wrong
-        }, {
-            classname: SyncPeerInnerspace_V1.name,
-        });
+        // const peer = new SyncPeerInnerspace_V1({
+        //     senderSpace: sourceSpace,
+        //     receiverSpace: destSpace,
+        //     receiverCoordinator: receiverCoordinator,
+        //     receiverMetaspace: metaspace,
+        //     receiverTempSpace: 0 as any, // placeholder this is wrong // just to get to compile
+        //     senderTempSpace: 0 as any, // placeholder this is wrong // just to get to compile
+        // }, {
+        //     classname: SyncPeerInnerspace_V1.name,
+        // });
+        const peer = new SyncPeerInnerspace_V1(0 as any, 0 as any, 0 as any, 0 as any);
 
         // 4. Sync C1 (First Pass)
         let resSync = await senderCoordinator.sync({

package/src/sync/sync-innerspace-deep-updates.respec.mts

@@ -100,16 +100,17 @@ await respecfully(sir, `Sync InnerSpaces (Deep Updates)`, async () => {
         const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
         const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
 
-        const peer = new SyncPeerInnerspace_V1({
-            senderSpace: sourceSpace,
-            receiverSpace: destSpace,
-            receiverCoordinator: receiverCoordinator,
-            receiverMetaspace: metaspace,
-            receiverTempSpace: 0 as any,
-            senderTempSpace: 0 as any,
-        }, {
-            classname: SyncPeerInnerspace_V1.name,
-        });
+        // const peer = new SyncPeerInnerspace_V1(
+        //     senderSpace: sourceSpace,
+        //     receiverSpace: destSpace,
+        //     receiverCoordinator: receiverCoordinator,
+        //     receiverMetaspace: metaspace,
+        //     receiverTempSpace: 0 as any, // just to get to compile
+        //     senderTempSpace: 0 as any, // just to get to compile
+        // }, {
+        //     classname: SyncPeerInnerspace_V1.name,
+        // });
+        const peer = new SyncPeerInnerspace_V1(0 as any, 0 as any, 0 as any, 0 as any);
 
         // 4. Run Sync
         console.log(`${lc} Running Sync...`);

package/src/sync/sync-innerspace-dest-ahead.respec.mts

@@ -110,16 +110,17 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
         const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
         const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
 
-        const peer = new SyncPeerInnerspace_V1({
-            senderSpace: sourceSpace,
-            receiverSpace: destSpace,
-            receiverCoordinator: receiverCoordinator,
-            receiverMetaspace: metaspace,
-            receiverTempSpace: 0 as any,// this is wrong just getting to build
-            senderTempSpace: 0 as any, // this is wrong just getting to build
-        }, {
-            classname: SyncPeerInnerspace_V1.name
-        });
+        // const peer = new SyncPeerInnerspace_V1({
+        //     senderSpace: sourceSpace,
+        //     receiverSpace: destSpace,
+        //     receiverCoordinator: receiverCoordinator,
+        //     receiverMetaspace: metaspace,
+        //     receiverTempSpace: 0 as any,// this is wrong just getting to build
+        //     senderTempSpace: 0 as any, // this is wrong just getting to build
+        // }, {
+        //     classname: SyncPeerInnerspace_V1.name
+        // });
+        const peer = new SyncPeerInnerspace_V1(0 as any, 0 as any, 0 as any, 0 as any);
 
         // 4. Run Sync (Source Pushes V1)
         console.log(`${lc} Running Sync...`);

package/src/sync/sync-innerspace-multiple-timelines.respec.mts

@@ -104,16 +104,18 @@ await respecfully(sir, `Sync InnerSpaces (Multiple Timelines)`, async () => {
         const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
         const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
 
-        const peer = new SyncPeerInnerspace_V1({
-            senderSpace: sourceSpace,
-            receiverSpace: destSpace,
-            receiverCoordinator: receiverCoordinator,
-            receiverMetaspace: metaspace,
-            receiverTempSpace: 0 as any,
-            senderTempSpace: 0 as any,
-        }, {
-            classname: SyncPeerInnerspace_V1.name,
-        });
+        // const peer = new SyncPeerInnerspace_V1({
+        //     senderSpace: sourceSpace,
+        //     receiverSpace: destSpace,
+        //     receiverCoordinator: receiverCoordinator,
+        //     receiverMetaspace: metaspace,
+        //     receiverTempSpace: 0 as any, // just to get to compile
+        //     senderTempSpace: 0 as any, // just to get to compile
+        // }, {
+        //     classname: SyncPeerInnerspace_V1.name,
+        // });
+        const peer = new SyncPeerInnerspace_V1(0 as any, 0 as any, 0 as any, 0 as any);
+        await peer.initialized;
 
         // 4. Run Sync (Push Both)
         console.log(`${lc} Running Sync...`);

package/src/sync/sync-innerspace-partial-update.respec.mts

@@ -112,18 +112,20 @@ await respecfully(sir, `Sync InnerSpaces (Partial Update)`, async () => {
         const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
         const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
 
-        const peer = new SyncPeerInnerspace_V1({
-            senderSpace: sourceSpace,
-            receiverSpace: destSpace,
-            receiverCoordinator: receiverCoordinator,
-            receiverMetaspace: metaspace,
-            receiverTempSpace: 0 as any,
-            senderTempSpace: 0 as any,
-        },
-            {
-                classname: SyncPeerInnerspace_V1.name,
-            }
-        );
+        // const peer = new SyncPeerInnerspace_V1({
+        //     senderSpace: sourceSpace,
+        //     receiverSpace: destSpace,
+        //     receiverCoordinator: receiverCoordinator,
+        //     receiverMetaspace: metaspace,
+        //     receiverTempSpace: 0 as any, // just to get to compile
+        //     senderTempSpace: 0 as any, // just to get to compile
+        // },
+        //     {
+        //         classname: SyncPeerInnerspace_V1.name,
+        //     }
+        // );
+        const peer = new SyncPeerInnerspace_V1(0 as any, 0 as any, 0 as any, 0 as any);
+        await peer.initialized;
 
         // 4. Run Sync (Source Pushes V2)
         console.log(`${lc} Running Sync...`);

package/src/sync/sync-innerspace.respec.mts

@@ -103,16 +103,18 @@ await respecfully(sir, `Sync InnerSpaces`, async () => {
         const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
 
         // Peer (The "Network")
-        const peer = new SyncPeerInnerspace_V1({
-            senderSpace: sourceSpace,   // "Client"
-            receiverSpace: destSpace,   // "Server"
-            receiverCoordinator: receiverCoordinator,
-            receiverMetaspace: metaspace,
-            senderTempSpace: 0 as any,
-            receiverTempSpace: 0 as any,
-        }, {
-            classname: SyncPeerInnerspace_V1.name,
-        });
+        // const peer = new SyncPeerInnerspace_V1({
+        //     senderSpace: sourceSpace,   // "Client"
+        //     receiverSpace: destSpace,   // "Server"
+        //     receiverCoordinator: receiverCoordinator,
+        //     receiverMetaspace: metaspace,
+        //     senderTempSpace: 0 as any,
+        //     receiverTempSpace: 0 as any,
+        // }, {
+        //     classname: SyncPeerInnerspace_V1.name,
+        // });
+        const peer = new SyncPeerInnerspace_V1(0 as any, 0 as any, 0 as any, 0 as any);
+        await peer.initialized;
 
         // 4. Run Sync
         console.log(`${lc} Running Sync...`);

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

@@ -14,21 +14,6 @@ import { SyncPeerData_V1, SyncPeerRel8ns_V1 } from '../sync-peer-types.mjs';
  * Options for creating a SyncPeerInnerspace instance.
  */
 export interface SyncPeerInnerspaceOptions {
-    /**
-     * sender's durable space.
-     * 
-     * will store control ibgibs (context, sync saga ibgib, control msg stones)
-     * here (and in {@link senderTempSpace}) throughout the process for audit trail.
-     */
-    senderSpace: IbGibSpaceAny;
-    /**
-     * sender's temporary space for the entire sync transaction.
-     * 
-     * In addition to control ibgibs which are stored in both temp and durable
-     * spaces, this temp space will be where domain ibgibs are stored that are
-     * received/created throughout the transaction until commit.
-     */
-    senderTempSpace: IbGibSpaceAny;
     /**
      * The "receiver" durable space (not temp). 
      *