@ibgib/core-gib 0.1.19 → 0.1.21

package/src/sync/graft-info/graft-info-helpers.mts

@@ -0,0 +1,308 @@
+import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { rel8 } from "@ibgib/ts-gib/dist/V1/transforms/rel8.mjs";
+
+import { IbGibSpaceAny } from "../../witness/space/space-base-v1.mjs";
+import { getFromSpace, putInSpace } from "../../witness/space/space-helper.mjs";
+import { applyTransforms } from "../../witness/space/reconciliation-space/reconciliation-space-helper.mjs";
+import {
+    GRAFT_INFO_ATOM,
+    GRAFT_BASE_REL8N_NAME,
+    GRAFT_ORPHAN_REL8N_NAME,
+    GRAFT_INFO_REL8N_NAME
+} from "./graft-info-constants.mjs";
+import { GraftInfoData_V1, GraftInfoIbGib_V1, GraftInfoIb_V1 } from "./graft-info-types.mjs";
+
+const lc = `[graft-info-helpers]`;
+
+/**
+ * Validates and constructs the `ib` object for a Graft Info ibGib.
+ */
+export async function getGraftInfoIb({
+    data
+}: {
+    data: GraftInfoData_V1
+}): Promise<string> {
+    if (!data.algo) { throw new Error(`(UNEXPECTED) data.algo required for GraftInfoIb (E: 8a9b0c1d2e3f4g5h)`); }
+
+    // graft_info algo
+    return [GRAFT_INFO_ATOM, data.algo].join(' ');
+}
+
+/**
+ * Parses a standard Graft Info 'ib' string.
+ */
+export async function parseGraftInfoIb({
+    ib
+}: {
+    ib: string
+}): Promise<GraftInfoIb_V1> {
+    try {
+        const parts = ib.split(' ');
+        if (parts[0] !== GRAFT_INFO_ATOM) { throw new Error(`Atom mismatch. Expected ${GRAFT_INFO_ATOM} (E: 8f03c92a95144b618821915632599266)`); }
+        if (parts.length < 2) { throw new Error(`Invalid graft info ib. Expected at least 2 parts. (E: 9c2b4c8a6d34469f8263544710183355)`); }
+
+        const algo = parts.slice(1).join(' '); // allow spaces in algo? usually single word but safe to join.
+
+        return {
+            atom: GRAFT_INFO_ATOM,
+            algo,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Creates a new GraftInfo ibGib.
+ */
+export async function createGraftInfo({
+    algo,
+    details,
+}: {
+    algo: string,
+    details?: string,
+}): Promise<GraftInfoIbGib_V1> {
+    const data: GraftInfoData_V1 = {
+        algo,
+        details,
+    };
+
+    const ib = await getGraftInfoIb({ data });
+
+    const res = await Factory_V1.stone({
+        ib,
+        data,
+        rel8ns: {}, // No default rel8ns (no 'ancestors' anymore)
+        parentPrimitiveIb: GRAFT_INFO_ATOM,
+        uuid: true,
+    });
+
+    return res as GraftInfoIbGib_V1;
+}
+
+/**
+ * Naive line-by-line text merge using LCS.
+ * Renamed to mergeTextLCS for clarity, but logic is generic LCS.
+ */
+export async function mergeTextLCS({
+    textA,
+    textB,
+}: {
+    textA: string,
+    textB: string,
+}): Promise<string> {
+    if (textA === textB) { return textA; }
+
+    const linesA = textA.split('\n');
+    const linesB = textB.split('\n');
+
+    const common = longestCommonSubsequence(linesA, linesB); // Array of { line, indexA, indexB }
+
+    let resultLines: string[] = [];
+    let currentA = 0;
+    let currentB = 0;
+
+    for (const match of common) {
+        // Add unique lines from A (before this match)
+        while (currentA < match.indexA) {
+            resultLines.push(linesA[currentA]);
+            currentA++;
+        }
+        // Add unique lines from B (before this match)
+        while (currentB < match.indexB) {
+            resultLines.push(linesB[currentB]);
+            currentB++;
+        }
+        // Add the common line
+        resultLines.push(match.line);
+        currentA++;
+        currentB++;
+    }
+
+    // Add remaining unique lines from A
+    while (currentA < linesA.length) {
+        resultLines.push(linesA[currentA]);
+        currentA++;
+    }
+    // Add remaining unique lines from B
+    while (currentB < linesB.length) {
+        resultLines.push(linesB[currentB]);
+        currentB++;
+    }
+
+    return resultLines.join('\n');
+}
+
+interface LcsMatch {
+    line: string;
+    indexA: number;
+    indexB: number;
+}
+
+function longestCommonSubsequence(a: string[], b: string[]): LcsMatch[] {
+    const m = a.length;
+    const n = b.length;
+    const dp: number[][] = Array(m + 1).fill(0).map(() => Array(n + 1).fill(0));
+
+    // Fill DP table
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (a[i - 1] === b[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1] + 1;
+            } else {
+                dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+            }
+        }
+    }
+
+    // Backtrack to find LCS
+    let i = m, j = n;
+    const lcs: LcsMatch[] = [];
+    while (i > 0 && j > 0) {
+        if (a[i - 1] === b[j - 1]) {
+            lcs.unshift({ line: a[i - 1], indexA: i - 1, indexB: j - 1 });
+            i--;
+            j--;
+        } else if (dp[i - 1][j] > dp[i][j - 1]) {
+            i--;
+        } else {
+            j--;
+        }
+    }
+    return lcs;
+}
+
+/**
+ * Grafts two divergent timelines by splicing missing DNA from one branch (Orphan) onto another (Base).
+ * 
+ * Logic:
+ * 1. Checks timestamps of tips. Earlier = Base, Later = Orphan.
+ * 2. Fetches DNA from Orphan's branch (since LCA).
+ * 3. Replays Orphan's DNA onto Base.
+ * 4. Creates GraftInfo linking Base and Orphan.
+ * 5. Rel8s the Result to GraftInfo.
+ */
+export async function graftTimelines({
+    tipA,
+    branchA,
+    tipB,
+    branchB,
+    space,
+    metaspace,
+}: {
+    tipA: IbGib_V1,
+    branchA: IbGib_V1[],
+    tipB: IbGib_V1,
+    branchB: IbGib_V1[],
+    space: IbGibSpaceAny,
+    metaspace: any,
+}): Promise<IbGib_V1> {
+    const lc = `[${graftTimelines.name}]`;
+    console.log(`${lc} [TEST DEBUG] starting... Metaspace present: ${!!metaspace}`);
+
+    // 1. Determine Base and Orphan based on timestamp
+    let baseTip: IbGib_V1;
+    let orphanTip: IbGib_V1; // The one providing the DNA to be replayed
+    let orphanBranch: IbGib_V1[];
+
+    const getTs = (ibGib: IbGib_V1) => {
+        const ms = ibGib.data?.timestampMs ?? 0;
+        if (!ms && ibGib.data?.timestamp) { return new Date(ibGib.data.timestamp).getTime(); }
+        return ms;
+    }
+
+    const tsA = getTs(tipA);
+    const tsB = getTs(tipB);
+
+    if (tsA <= tsB) {
+        // A is earlier (or equal), use A as base
+        baseTip = tipA;
+        orphanTip = tipB;
+        orphanBranch = branchB;
+    } else {
+        // B is earlier, use B as base
+        baseTip = tipB;
+        orphanTip = tipA;
+        orphanBranch = branchA;
+    }
+
+    const baseAddr = getIbGibAddr({ ibGib: baseTip });
+    const orphanAddr = getIbGibAddr({ ibGib: orphanTip });
+
+    // 2. Gather DNA addresses from the Orphan branch
+    const dnaAddrsToApply: string[] = [];
+    for (const ibGib of orphanBranch) {
+        const dnas = ibGib.rel8ns?.dna || [];
+        dnaAddrsToApply.push(...dnas);
+    }
+
+    if (dnaAddrsToApply.length === 0) {
+        return baseTip;
+    }
+
+    // 3. Fetch the DNA stones
+    const dnaRes = await getFromSpace({ space, addrs: dnaAddrsToApply });
+    if (!dnaRes.success || !dnaRes.ibGibs) {
+        throw new Error(`Failed to fetch DNA stones for replay. (E: 3a2b1c4d5e6f7g8h)`);
+    }
+    const allDnaIbGibs = dnaRes.ibGibs;
+
+    // 4. Replay Transforms onto Base
+    const createdIbGibs_Running: IbGib_V1[] = [];
+
+    const mergedTip = await applyTransforms({
+        src: baseTip,
+        dnaAddrsToApplyToStoreVersion: [...dnaAddrsToApply],
+        allLocalIbGibs: allDnaIbGibs,
+        createdIbGibs_Running,
+    });
+
+    // 5. Persist the new stones
+    await putInSpace({ space, ibGibs: createdIbGibs_Running });
+
+    // 6. Create Graft Info
+    const graftInfo = await createGraftInfo({
+        algo: 'optimistic_dna_replay',
+        details: `Replayed ${dnaAddrsToApply.length} transforms from orphan (${orphanAddr}) onto base (${baseAddr}).`,
+    });
+
+    // Add relations via rel8
+    const graftInfoRel8nsToAdd = {
+        [GRAFT_BASE_REL8N_NAME]: [baseAddr],
+        [GRAFT_ORPHAN_REL8N_NAME]: [orphanAddr],
+    };
+
+    const { newIbGib: graftInfoWithRel8ns } = await rel8({
+        src: graftInfo,
+        rel8nsToAddByAddr: graftInfoRel8nsToAdd,
+        dna: true,
+    });
+    // Persist this update
+    await putInSpace({ space, ibGibs: [graftInfoWithRel8ns] });
+
+    // 7. Link GraftInfo to Result via 'graftinfo' rel8n
+    const graftInfoAddr = getIbGibAddr({ ibGib: graftInfoWithRel8ns });
+    const { newIbGib: finalIbGib, dnas: rel8Dnas, intermediateIbGibs } = await rel8({
+        src: mergedTip,
+        rel8nsToAddByAddr: {
+            [GRAFT_INFO_REL8N_NAME]: [graftInfoAddr],
+        },
+        dna: true, // Auto-link 'dna'
+        nCounter: true,
+    });
+
+    // Persist final result
+    const finalStones = [finalIbGib, ...(rel8Dnas || []), ...(intermediateIbGibs || [])];
+    await putInSpace({ space, ibGibs: finalStones });
+
+    // 8. Register New Tip in Metaspace (CRITICAL for updating Timeline Index)
+    if (metaspace && metaspace.registerNewIbGib) {
+        await metaspace.registerNewIbGib({ ibGib: finalIbGib, space });
+    }
+
+    return finalIbGib;
+}

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

@@ -0,0 +1,83 @@
+import { iReckon, respecfully, ifWe, ifWeMight } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { mergeTextLCS } from './graft-info-helpers.mjs';
+
+const maam = `[${import.meta.url}]`;
+const sir = maam;
+
+await respecfully(sir, 'Graft Info Helpers', async () => {
+
+    await respecfully(sir, 'mergeTextLCS', async () => {
+
+        await ifWe(sir, 'mergeTextLCS should interleave unique lines (A then B)', async () => {
+            const textA = "Line 1\nLine A\nLine 3";
+            const textB = "Line 1\nLine B\nLine 3";
+            const res = await mergeTextLCS({ textA, textB });
+            const expected = "Line 1\nLine A\nLine B\nLine 3";
+            iReckon(sir, res).asTo('result').isGonnaBe(expected);
+        });
+
+        await ifWe(sir, 'mergeTextLCS should handle insertions', async () => {
+            const textA = "Line 1\nLine 3";
+            const textB = "Line 1\nLine 2\nLine 3";
+            const res = await mergeTextLCS({ textA, textB });
+            const expected = "Line 1\nLine 2\nLine 3";
+            iReckon(sir, res).asTo('result').isGonnaBe(expected);
+        });
+
+        await ifWe(sir, 'mergeTextLCS should handle appends', async () => {
+            const textA = "Line 1";
+            const textB = "Line 1\nLine 2";
+            const res = await mergeTextLCS({ textA, textB });
+            const expected = "Line 1\nLine 2";
+            iReckon(sir, res).asTo('result').isGonnaBe(expected);
+        });
+
+        await ifWe(sir, 'mergeTextLCS should handle simultaneous list additions', async () => {
+            const textA = "- Item 1\n- Item 2\n- Item A";
+            const textB = "- Item 1\n- Item 2\n- Item B";
+            const res = await mergeTextLCS({ textA, textB });
+
+            // Expected: Common (1, 2) then A then B.
+            const expected = "- Item 1\n- Item 2\n- Item A\n- Item B";
+            iReckon(sir, res).asTo('result').isGonnaBe(expected);
+        });
+
+        await ifWe(sir, 'mergeTextLCS should handle distinct modifications in code block', async () => {
+            const textA = `function foo() {
+    console.log("start");
+    doA();
+    console.log("end");
+}`;
+            const textB = `function foo() {
+    console.log("start");
+    doB();
+    console.log("end");
+}`;
+            const res = await mergeTextLCS({ textA, textB });
+
+            const expected = `function foo() {
+    console.log("start");
+    doA();
+    doB();
+    console.log("end");
+}`;
+            iReckon(sir, res).asTo('result').isGonnaBe(expected);
+        });
+
+        await ifWe(sir, 'mergeTextLCS should return same string if identical', async () => {
+            const textA = "Hello";
+            const res = await mergeTextLCS({ textA, textB: textA });
+            iReckon(sir, res).asTo('result').isGonnaBe(textA);
+        });
+
+    });
+
+    await respecfully(sir, 'graftTimelines', async () => {
+        // We need a more complex setup to test this properly (mock space, etc.)
+        // For now, this placeholder ensures the test file runs.
+        await ifWe(sir, 'graftTimelines placeholders', async () => {
+            iReckon(sir, true).isGonnaBeTrue();
+        });
+    });
+
+});

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

@@ -0,0 +1,33 @@
+import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { GRAFT_INFO_ATOM } from "./graft-info-constants.mjs";
+
+export interface GraftInfoIb_V1 {
+    atom: typeof GRAFT_INFO_ATOM;
+    algo: string; // e.g. "optimistic_dna_replay", "text_lcs", "manual"
+}
+
+export interface GraftInfoData_V1 extends IbGibData_V1 {
+    /**
+     * The algorithm or strategy used to perform the graft.
+     */
+    algo: string;
+    /**
+     * Optional details about the graft, e.g. validation results or specifics about conflicts resolved.
+     */
+    details?: string;
+}
+
+export interface GraftInfoRel8ns_V1 extends IbGibRel8ns_V1 {
+    /**
+     * The 'base' of the graft (the earlier tip, usually).
+     * This is the timeline we are grafting ONTO.
+     */
+    graftbase?: string[];
+    /**
+     * The 'orphan' tip (the later tip, usually) effectively grafted into the base.
+     * This is the branch that ends here, its DNA spliced into the base.
+     */
+    graftorphan?: string[];
+}
+
+export interface GraftInfoIbGib_V1 extends IbGib_V1<GraftInfoData_V1, GraftInfoRel8ns_V1> { }

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

@@ -0,0 +1,149 @@
+/**
+ * @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 };
+}
+
+import { graftTimelines, mergeTextLCS } from '../graft-info/graft-info-helpers.mjs';
+
+/**
+ * Optimistically grafts two divergent timelines by inspecting DNA and replaying transforms.
+ */
+export async function mergeDivergentTimelines({
+    tipA,
+    tipB,
+    space,
+    metaspace,
+}: {
+    tipA: IbGib_V1,
+    tipB: IbGib_V1,
+    space: IbGibSpaceAny,
+    metaspace: any, // MetaspaceService type
+}): Promise<IbGib_V1> {
+    const lc = `[${mergeDivergentTimelines.name}]`;
+
+    // 1. Find LCA & Branches
+    const { lcaAddr, branchA, branchB } = await findLCA({ tipA, tipB, space });
+
+    // 2. Delegate to Graft Engine
+    // The graft engine handles timestamp verification, DNA fetching, replay, and Stone creation.
+    const result = await graftTimelines({
+        tipA,
+        branchA,
+        tipB,
+        branchB,
+        space,
+        metaspace,
+    });
+
+    return result;
+}