@ibgib/core-gib 0.1.19 → 0.1.20

package/src/sync/merge-info/merge-info-helpers.respec.mts

@@ -0,0 +1,41 @@
+/**
+ * @module merge-info-helpers.respec
+ */
+import { iReckon, respecfully, ifWe, ifWeMight } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { mergeText } from './merge-info-helpers.mjs';
+
+const maam = `[${import.meta.url}]`;
+const sir = maam;
+
+await respecfully(sir, 'Merge Info Helpers', async () => {
+
+    await respecfully(sir, 'mergeText', async () => {
+
+        await ifWeMight(sir, 'mergeText should concat different strings', async () => {
+            const textA = "Hello";
+            const textB = "World";
+            const res = await mergeText({ textA, textB });
+            iReckon(sir, res).asTo('result').isGonnaBeTruthy();
+            iReckon(sir, res.includes(textA)).asTo('includes A').isGonnaBeTruthy();
+            iReckon(sir, res.includes(textB)).asTo('includes B').isGonnaBeTruthy();
+            iReckon(sir, res.includes('MERGE SEPARATOR')).asTo('includes separator').isGonnaBeTruthy();
+        });
+
+        await ifWeMight(sir, 'mergeText should return same string if identical', async () => {
+            const textA = "Hello";
+            const res = await mergeText({ textA, textB: textA });
+            iReckon(sir, res).asTo('result').isGonnaBe(textA);
+        });
+
+    });
+
+    await respecfully(sir, 'combineDivergentTimelines', async () => {
+
+        await ifWeMight(sir, 'combineDivergentTimelines should work (Stub)', async () => {
+            // Validation of stub for now, just to ensure scaffolding works.
+            iReckon(sir, true).asTo('stub executed').isGonnaBeTruthy();
+        });
+
+    });
+
+});

package/src/sync/merge-info/merge-info-types.mts

@@ -0,0 +1,28 @@
+import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { MERGE_INFO_ATOM } from "./merge-info-constants.mjs";
+
+export interface MergeInfoIb_V1 {
+    atom: typeof MERGE_INFO_ATOM;
+    algo: string; // e.g. "optimistic", "text", "manual"
+}
+
+export interface MergeInfoData_V1 extends IbGibData_V1 {
+    /**
+     * The algorithm or strategy used to perform the merge.
+     */
+    algo: string;
+    /**
+     * Optional details about the merge, e.g. validation results or specifics about conflicts resolved.
+     */
+    details?: string;
+}
+
+export interface MergeInfoRel8ns_V1 extends IbGibRel8ns_V1 {
+    /**
+     * The ibGibs that were merged together.
+     * For a timeline merge, these are the tips of the divergent branches.
+     */
+    ancestors?: string[];
+}
+
+export interface MergeInfoIbGib_V1 extends IbGib_V1<MergeInfoData_V1, MergeInfoRel8ns_V1> { }

package/src/sync/strategies/conflict-optimistic.mts

@@ -0,0 +1,208 @@
+/**
+ * @module conflict-optimistic
+ * 
+ * Implements the Optimistic Conflict Resolution Strategy.
+ * 
+ * Logic:
+ * 1. findLCA: Traverses `past` to find common ancestor.
+ * 2. mergeDivergentTimelines: Replays DNA to create a merged tip.
+ */
+
+import { IbGib_V1, IbGibRel8ns_V1, IbGibData_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
+import { getFromSpace, putInSpace } from '../../witness/space/space-helper.mjs';
+import { mut8Timeline } from '../../timeline/timeline-api.mjs';
+
+const lc = `[conflict-optimistic]`;
+
+export interface LCAResult {
+    lcaAddr: string;
+    branchA: IbGib_V1[]; // Path from LCA to Tip A (exclusive of LCA)
+    branchB: IbGib_V1[]; // Path from LCA to Tip B (exclusive of LCA)
+}
+
+/**
+ * Finds the Last Common Ancestor (LCA) between two divergent timelines.
+ * 
+ * Note: simplistic implementation assuming simple linear divergence.
+ * Complex DAGs might require more robust graph traversal.
+ */
+export async function findLCA({
+    tipA,
+    tipB,
+    space,
+}: {
+    tipA: IbGib_V1,
+    tipB: IbGib_V1,
+    space: IbGibSpaceAny,
+}): Promise<LCAResult> {
+    // 1. Load history for both
+    // Optimization: Just load 'past' array if available.
+    // Ideally we assume 'past' is full history for V1.
+
+    // Check if one is ancestor of another first?
+    const pastA = tipA.rel8ns?.past || [];
+    const pastB = tipB.rel8ns?.past || [];
+    const addrA = getIbGibAddr({ ibGib: tipA });
+    const addrB = getIbGibAddr({ ibGib: tipB });
+
+    // Is B in A's past?
+    if (pastA.includes(addrB)) { return { lcaAddr: addrB, branchA: [], branchB: [] }; } // Not a divergence, just an update.
+    // Is A in B's past?
+    if (pastB.includes(addrA)) { return { lcaAddr: addrA, branchA: [], branchB: [] }; }
+
+    // Find intersection
+    let lcaAddr: string | undefined;
+
+    // Iterate backwards through A's past
+    // The *latest* entry in A's past that is also in B's past (or is B itself, but we checked that)
+    // Actually, 'past' is usually ordered? V1 convention is accretive, so order matches evolution.
+    // But 'past' array order isn't strictly guaranteed by schema to be chronological, but robust implementations do so.
+    // Let's assume Set intersection.
+
+    const setPastB = new Set(pastB);
+    // Find the *latest* item in pastA that is in setPastB.
+    // We assume pastA is ordered [older -> newer].
+    for (let i = pastA.length - 1; i >= 0; i--) {
+        const candidate = pastA[i];
+        if (setPastB.has(candidate)) {
+            lcaAddr = candidate;
+            break;
+        }
+    }
+
+    if (!lcaAddr) {
+        // Fallback: check if they share the SAME TJP (they should if they are same timeline).
+        // If they share TJP but no common past, the TJP itself is the LCA.
+        const tjpA = tipA.rel8ns?.tjp?.[0];
+        const tjpB = tipB.rel8ns?.tjp?.[0];
+        if (tjpA && tjpA === tjpB) {
+            lcaAddr = tjpA;
+        } else {
+            throw new Error(`No LCA found for divergences. Are they the same timeline? (E: 81aa17f0e34b4138ad1743a60a76f27b)`);
+        }
+    }
+
+    // 2. Reconstruct Branches
+    // We need the actual ibGib objects from LCA to Tips to inspect DNA.
+    // This requires fetching from Space.
+
+    // Helper to get path from LCA to Tip
+    const getPath = async (tip: IbGib_V1, past: string[], lca: string): Promise<IbGib_V1[]> => {
+        const pathAddrs: string[] = [];
+        let foundLca = false;
+        for (const addr of past) {
+            if (foundLca) {
+                pathAddrs.push(addr);
+            } else if (addr === lca) {
+                foundLca = true;
+            }
+        }
+        pathAddrs.push(getIbGibAddr({ ibGib: tip }));
+
+        // Fetch all
+        const res = await getFromSpace({ space, addrs: pathAddrs });
+        if (!res.success || !res.ibGibs) { throw new Error(`Failed to fetch history branch. (E: 7904097405be4a27b871c5031631553c)`); }
+        return res.ibGibs;
+    };
+
+    const branchA = await getPath(tipA, pastA, lcaAddr);
+    const branchB = await getPath(tipB, pastB, lcaAddr);
+
+    return { lcaAddr, branchA, branchB };
+}
+
+/**
+ * Optimistically merges two divergent timelines by inspecting DNA.
+ */
+export async function mergeDivergentTimelines({
+    tipA,
+    tipB,
+    space,
+    metaspace,
+}: {
+    tipA: IbGib_V1,
+    tipB: IbGib_V1,
+    space: IbGibSpaceAny,
+    metaspace: any, // MetaspaceService type
+}): Promise<IbGib_V1> {
+
+    // 1. Find LCA & Branches
+    const { lcaAddr, branchA, branchB } = await findLCA({ tipA, tipB, space });
+
+    // 2. DNA Analysis & Reducing
+    // We need to accumulate the "changes" from A and "changes" from B.
+    // For V1 simple objects, this means extracting the `dataToAddOrPatch` from each DNA transform.
+
+    const extractChanges = async (branch: IbGib_V1[]): Promise<any> => {
+        let accumulatedData = {};
+        for (const ibGib of branch) {
+            // Check DNA
+            const dnaRel = ibGib.rel8ns?.dna;
+            if (!dnaRel || dnaRel.length === 0) continue;
+
+            // Load DNA (usually optimized to be in-memory if we just loaded the timeline? 
+            // no, DNA is a separate stone. we might need to fetch it.)
+            const dnaRes = await getFromSpace({ space, addrs: dnaRel });
+            const dnaIbGibs = dnaRes.ibGibs || [];
+
+            for (const dna of dnaIbGibs) {
+                // Inspect DNA data. 
+                // We expect 'mut8' transform DNA.
+                // The DNA *data* contains the args used in the transform.
+                if (dna.data && (dna.data as any).dataToAddOrPatch) {
+                    Object.assign(accumulatedData, (dna.data as any).dataToAddOrPatch);
+                }
+            }
+        }
+        return accumulatedData;
+    };
+
+    const changesA = await extractChanges(branchA);
+    const changesB = await extractChanges(branchB);
+
+    // 3. Conflict Resolution Strategy (Optimistic: Merge All)
+    // Conflict collision: If A and B changed the SAME field.
+    // Strategy: Last Write Wins? Or deterministic tie-break?
+    // Let's default to: Apply A, then Apply B. B wins collisions.
+    // (Ideally we flag this for user review, but "Optimistic" means we presume it's fine).
+
+    const mergedChanges = { ...changesA, ...changesB };
+
+    // 4. Create Merge Transform
+    // We create a NEW mut8 on top of tipA (or tipB).
+    // Let's pick tipA as the "base" to apply the merge to.
+    // But we must also link tipB as an ancestor?
+    // Standard mut8Timeline only supports linear ancestry.
+    // We need a "Merge" transform that rel8s both.
+
+    // Use mut8Timeline on tipA, applying the *missing* changes from B, 
+    // AND explicitly adding tipB to the 'ancestor' (or 'merge_ancestor'?) rel8n.
+
+    // Actually, simply applying 'mergedChanges' to tipA might be redundant for the parts A already did.
+    // We only need to apply 'changesB' to tipA? 
+    // Wait, if B changed field-X to 'foo' and A touched field-Y. 
+    // We apply changesB (foo) to tipA. Result has both.
+    // What if B changed field-X to 'foo' and A changed field-X to 'bar'.
+    // changesB overwrites. Result is 'foo'.
+
+    // So: Apply changesB to tipA.
+
+    const result = await mut8Timeline({
+        timeline: tipA,
+        mut8Opts: {
+            dataToAddOrPatch: changesB, // Apply B's changes onto A
+            // We want to record that B is also a parent.
+            // mut8Timeline might not expose 'otherAncestors'.
+            // required to verify this API capabilities.
+        },
+        space,
+        metaspace,
+    });
+
+    // Ideally we'd modify the result to add 'past' link to tipB.
+    // But for now, let's just achieve data convergence.
+
+    return result;
+}

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

@@ -0,0 +1,194 @@
+/**
+ * @module sync-conflict.respec
+ *
+ * Verifies Conflict Resolution strategies in SyncSagaCoordinator.
+ * Reproduces divergence scenarios and asserts resolution behavior.
+ */
+
+import {
+    respecfully, lastOfAll, ifWe, iReckon,
+    ifWeMight
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const maam = `[${import.meta.url}]`, sir = maam;
+import { delay, extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+
+import { SyncSagaCoordinator } from './sync-saga-coordinator.mjs';
+import { getFromSpace } from '../witness/space/space-helper.mjs';
+import { Metaspace_Innerspace } from '../witness/space/metaspace/metaspace-innerspace/metaspace-innerspace.mjs';
+import { InnerSpace_V1 } from '../witness/space/inner-space/inner-space-v1.mjs';
+import { createTimelineRootHelper, getTestKeystoneServiceHelper } from '../agent-helpers.mjs';
+import { mut8Timeline } from '../timeline/timeline-api.mjs';
+import { SyncPeerInnerspace_V1 } from './sync-peer/sync-peer-innerspace-v1.mjs';
+import { DEFAULT_INNER_SPACE_DATA_V1 } from '../witness/space/inner-space/inner-space-types.mjs';
+import { toDto } from '../common/other/ibgib-helper.mjs';
+import { SyncConflictStrategy, SyncSagaInfo } from './sync-types.mjs';
+import { IbGibData_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+interface TestData extends IbGibData_V1 {
+    text?: string;
+    fieldA?: string;
+    fieldB?: string;
+}
+
+const logalot = true;
+const lc = `[sync-conflict.respec]`;
+
+await respecfully(sir, `Sync Conflict Resolution`, async () => {
+
+    let metaspace: Metaspace_Innerspace;
+    let sourceSpace: InnerSpace_V1;
+    let destSpace: InnerSpace_V1;
+
+    await respecfully(sir, `Scenario: Simple Divergence (Field A vs Field B)`, async () => {
+        // 1. Setup Spaces
+        metaspace = new Metaspace_Innerspace(undefined);
+        await metaspace.initialize({
+            getFnAlert: () => async ({ title, msg }) => { console.log(`[Alert] ${title}: ${msg}`); },
+            getFnPrompt: () => async ({ title, msg }) => { console.log(`[Prompt] ${title}: ${msg}`); return ''; },
+            getFnPromptPassword: () => async (title, msg) => { console.log(`[PromptPwd] ${title}: ${msg}`); return null; },
+        });
+        while (!metaspace.initialized) { await delay(10); }
+
+        const defaultLocalUserSpace = await metaspace.getLocalUserSpace({ lock: false });
+        await defaultLocalUserSpace!.initialized;
+
+        sourceSpace = new InnerSpace_V1({
+            ...DEFAULT_INNER_SPACE_DATA_V1,
+            name: 'source',
+            uuid: 'source_uuid',
+            description: 'source test space',
+        });
+        await sourceSpace.initialized;
+
+        destSpace = new InnerSpace_V1({
+            ...DEFAULT_INNER_SPACE_DATA_V1,
+            name: 'dest',
+            uuid: 'dest_uuid',
+            description: 'dest test space',
+        });
+        await destSpace.initialized;
+
+        // 2. Seed Common History (V0 -> V1)
+        console.log(`${lc} Creating Common History...`);
+        const root = await createTimelineRootHelper<TestData>({
+            ib: 'timeline_root',
+            data: { type: 'root', text: 'v0' },
+            space: sourceSpace,
+        });
+        // Sync root to dest immediately so they start synced
+        await metaspace.put({ ibGib: root, space: destSpace });
+        await metaspace.registerNewIbGib({ ibGib: root, space: destSpace });
+
+
+        // Create V1 (Common)
+        const v1_Source = await mut8Timeline<TestData>({
+            timeline: root,
+            mut8Opts: { dataToAddOrPatch: { text: 'v1_common' } },
+            metaspace,
+            space: sourceSpace,
+        });
+        // Sync V1 to dest
+        await metaspace.put({ ibGib: v1_Source, space: destSpace });
+        await metaspace.registerNewIbGib({ ibGib: v1_Source, space: destSpace });
+
+        const resGetDest = await getFromSpace({ space: destSpace, addr: getIbGibAddr({ ibGib: v1_Source }) });
+        if (!resGetDest.success || !resGetDest.ibGibs || resGetDest.ibGibs.length === 0) {
+            throw new Error(`Failed to retrieve v1_Dest from destSpace. (E: a1b2c3d4e5f6g7h8i9j0)`);
+        }
+        const v1_Dest = resGetDest.ibGibs[0];
+
+
+        // 3. Create Divergence (V2a vs V2b)
+        console.log(`${lc} Creating Divergence...`);
+
+        // Source: V1 -> V2a (Edit Field A)
+        const v2a = await mut8Timeline<TestData>({
+            timeline: v1_Source,
+            mut8Opts: { dataToAddOrPatch: { fieldA: 'source_edit' } },
+            metaspace,
+            space: sourceSpace,
+        });
+
+        // Dest: V1 -> V2b (Edit Field B)
+        const v2b = await mut8Timeline<TestData>({
+            timeline: v1_Dest,
+            mut8Opts: { dataToAddOrPatch: { fieldB: 'dest_edit' } },
+            metaspace,
+            space: destSpace,
+        });
+
+        // Verify Divergence
+        const tjpAddr = root.rel8ns!.tjp![0]; // wait, root IS tjp, so no tjp rel8n...
+        // Actually root frame has isTjp: true.
+        // v1 has tjp: [v0_gib].
+        console.log(`${lc} Divergence created.`);
+
+
+        // 4. Run Sync (Optimistic)
+        console.log(`${lc} Setting up Coordinators...`);
+        const mockKeystone = await getTestKeystoneServiceHelper();
+        const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
+        const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
+
+        const peer = new SyncPeerInnerspace_V1({
+            senderSpace: sourceSpace,
+            receiverSpace: destSpace,
+            receiverCoordinator,
+            receiverMetaspace: metaspace,
+        });
+
+        // Verify Receiver has correct KV (Pre-Sync Check)
+        // This ensures the conflict precondition exists.
+        await ifWe(sir, 'verify receiver KV pre-sync', async () => {
+            const destKV = await receiverCoordinator.getKnowledgeVector({
+                space: destSpace,
+                metaspace,
+                domainIbGibs: [v1_Dest]
+            });
+            const v1TjpAddr = v1_Dest.rel8ns?.tjp?.[0] || getIbGibAddr({ ibGib: v1_Dest }); // v1 might be tjp if it was root, but here v1 is child of root
+            // Actually v1 has tjp rel8n.
+            const destTip = destKV[v1TjpAddr];
+            iReckon(sir, !!destTip).asTo(`Dest KV has timeline tip for ${v1TjpAddr}`).isGonnaBeTruthy();
+            if (!destTip) {
+                throw new Error(`Test Setup Fail: Dest Space does not have index for timeline ${v1TjpAddr}. Seeding failed. (E: 8a9b0c1d)`);
+            }
+        });
+
+        console.log(`${lc} Running Sync (ConflictStrategy: optimistic)...`);
+
+        let resSync: SyncSagaInfo | undefined;
+        try {
+            resSync = await senderCoordinator.sync({
+                peer,
+                source: sourceSpace,
+                dest: destSpace,
+                metaspace,
+                domainIbGibs: [v2a],
+                conflictStrategy: SyncConflictStrategy.optimistic,
+                // identity: undefined as any, // Not needed? If removed, it uses session identity.
+                // identitySecret: undefined as any,
+                // explicit useSessionIdentity: true is default
+            });
+
+            await resSync.done;
+            console.log(`${lc} Sync Complete.`);
+        } catch (e) {
+            console.error(`${lc} Sync Failed with Error:`, e);
+            iReckon(sir, false).asTo(`Sync failed with error: ${e}`).isGonnaBeTruthy();
+            return; // Exit test early
+        }
+
+        // 5. Verification
+        // Expectation: Both Spaces should now have a NEW tip (V3) that merges V2a and V2b.
+
+        const resSourceTip = await getFromSpace({ space: sourceSpace, addr: getIbGibAddr({ ibGib: v2a }) });
+
+        await ifWe(sir, `verify merge happened`, async () => {
+            // We expect a new tip that is NOT v2a or v2b
+            // For now, valid failure is that this code doesn't start or completes without merge.
+            iReckon(sir, true).asTo('Merge Verification Not Yet Implemented').isGonnaBeFalse();
+        });
+    });
+
+});

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

@@ -25,7 +25,7 @@ const lc = `[sync-innerspace-constants.respec]`;
 
 await respecfully(sir, `Sync Constants (No TJP)`, async () => {
 
-    await ifWeMight(sir, `Verify Constants Sync`, async () => {
+    await ifWe(sir, `Verify Constants Sync`, async () => {
         // 1. Setup Spaces
         const metaspace = new Metaspace_Innerspace(undefined);
         await metaspace.initialize({

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

@@ -118,7 +118,6 @@ await respecfully(sir, `Sync InnerSpaces (Deep Updates)`, async () => {
             localSpace: sourceSpace,
             metaspace: metaspace,
             domainIbGibs: [commentV2], // Sync the TIP
-            useSessionIdentity: false,
         });
 
         await resSync.done;

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

@@ -33,7 +33,7 @@ await respecfully(sir, `Sync InnerSpaces`, async () => {
     let sourceSpace: InnerSpace_V1;
     let destSpace: InnerSpace_V1;
 
-    await ifWe(sir, `Basic Push Sync (Source -> Dest)`, async () => {
+    await respecfully(sir, `Basic Push Sync (Source -> Dest)`, async () => {
         // 1. Setup Spaces
         metaspace = new Metaspace_Innerspace(undefined);
         await metaspace.initialize({