@ibgib/core-gib 0.1.20 → 0.1.22

package/src/sync/README.md

@@ -8,27 +8,36 @@ The synchronization process is modeled as a "Saga" — a linear but distributed
 
 *   **[SyncSagaIbGib_V1](file:./sync-types.mts)**: The timeline that encapsulates the entire sync process. This acts as the **shared audit trail**. By the end of a successful sync, both the Local and Remote nodes will have an identical copy of this saga timeline, proving exactly what was exchanged and when.
 *   **[SyncSagaCoordinator](file:./sync-saga-coordinator.mts)**: The "Driver" (State Machine) that manages the saga. It is symmetric: both Alice (Source) and Bob (Destination) use the exact same coordinator logic to evolve the saga frame.
-*   **[SyncPeerWitness](file:./sync-peer/sync-peer-types.mts)**: The interface for the "Transport Layer". It abstracts the communication channel (Method Call, HTTP, WebSocket) into a standard Witness pattern.
+*   **[SyncPeerWitness](file:./sync-peer/sync-peer-types.mts)**: The interface for the "Transport Layer". It abstracts the communication channel (Method Call, HTTP, WebSocket) into a simple Witness pattern: `(SyncSagaContextIbGib_V1) => Promise<SyncSagaContextIbGib_V1>` ("ping-pong" exchange).
     *   **[SyncPeer_V1](file:./sync-peer/sync-peer-v1.mts)** provides the base plumbing.
     *   Concrete implementations (e.g., in-memory) handle the actual byte transfer.
-*   **[SyncSagaContextIbGib_V1](file:./sync-saga-context/sync-saga-context-types.mts)**: The "Transport Envelope". This is the payload passed to the Witness. It contains the current Saga Frame, the Message Stones (Data), and any cryptographic proofs required for the step.## Conflict Resolution & Protocol Refinements
-
-### Unified Ack Protocol
-To optimize the handshake, the `Ack` frame now carries both synchronization data (requests/offers) AND conflict information.
-*   **Conflicts**: If the Receiver detects divergence (multiple timeline tips), it includes a `conflicts` array in the `Ack`.
-*   **Structure**: Each conflict includes the `tjpAddr`, `localAddr` (Receiver's Tip), `remoteAddr` (Sender's Tip), and crucially `timelineAddrs` (History).
-
-### Iterative Delta Protocol (Ping-Pong)
-The `Delta` phase is no longer a single push. It is an iterative negotiation:
-1.  **Symmetrical**: Both Sender and Receiver can send `Delta` frames.
-2.  **Payloads**: Frames carry `payloadAddrs` (manifest) and the actual data is persisted to the peer's space.
-3.  **Requests**: A Delta can include `requests` (e.g., asking for missing conflict history).
-4.  **Merge**: If a peer resolves a conflict locally (using `optimistic` strategies), the resulting **Merge Frame** is added to the outgoing payload.
-5.  **Completion**: A `Delta` frame includes a `proposeCommit` flag. If one peer sets this and the other has nothing to add, the session transitions to `Commit`.
-
-### Commit Phase
-*   **Persistence**: The `Commit` frame signals success.
-*   **Cleanup**: The `SyncPeer` is responsible for moving verified `ibGibs` from the temporary saga space to the persistent domain space.
+*   **[SyncSagaContextIbGib_V1](file:./sync-saga-context/sync-saga-context-types.mts)**: The "Transport Envelope" passed to the `SyncPeer_V1`. 
+    * Contains the current Saga Frame, the Message Stone(s) (Data), and any cryptographic proofs required for the step.
+
+## Workflow
+
+Init -> Ack -> Delta(s) -> Conflict/Commit via "ping pong" exchange.
+
+1.  **Init**: Sender initiates sync.
+    * Creates the `SyncSagaIbGib_V1` with an `Init` msg frame containing knowledge about domain ibgibs to sync.
+    * Optionally creates session keystone based off of Sender's primary keystone.
+    * Wraps the saga ibgib in a `SyncSagaContextIbGib_V1` and passes to the `SyncPeer_V1`.
+2.  **Ack**: Receiver gets incoming `SyncSagaContextIbGib_V1` and passes to its `SyncSagaCoordinator`.
+    * Handles the `Init` frame, comparing knowledge with Receiver's own status of each timeline/stone in domain ibgibs.
+    * Creates an `Ack` frame, evolves the `SyncSagaIbGib_V1` with this, wraps in `SyncSagaContextIbGib_V1` and returns to Sender.
+      * The `Ack` frame carries both synchronization data (requests/offers) AND conflict information.
+      * If the Receiver detects divergence (timeline tips differ and receiver doesn't recognize Sender's tip), it includes a `conflicts` array.
+      * Each conflict includes the `tjpAddr`, `localAddr` (Receiver's Tip), `remoteAddr` (Sender's Tip), and crucially `timelineAddrs` (History).
+3.  **Delta**: Sender now has enough information to send `Delta` frame if needed.
+    * Both Sender and Receiver can send `Delta` frames.
+    * `Delta` frames soft link to `payloadAddrsControl` and `payloadAddrsDomain` and act as a manifest, while the actual data transmitted happens according to the `SyncPeer_V1` implementation.
+      * `SyncPeer_V1.payloadIbGibsDomainReceived$` is an observable for the actual domain payload ibgibs transmitted.
+      * So the a node sends domain payloads out in bulk to the `SyncPeer_V1`, receives the return saga ibgib with a manifest, but may have to wait for the observable to complete to actually process the ibgibs.
+    * `Delta` frame can include `requests` (e.g., asking for missing conflict history).
+    * Once no deltas required, `Delta` frame sets `proposeCommit` flag. If the other has nothing to add, the session transitions to `Commit`.
+4.  **Commit**: When receive `Delta` frame with `proposeCommit`,  should trigger the receiver of this to start its commit. If that is successful, it should return a `Commit` frame, which signals the commit was successful on their end. When this `Commit` frame is received, this end should not perform its own commit. 
+    * For local-only syncs, the `SyncPeer_V1` implementation is responsible for moving verified `ibGibs` from the temporary saga space to the durable/persistent domain space.
+*   From each endpoint's POV, the cleanup should remove the temp spaces used, in addition to any other required transaction cleanup (like closing any connections). 
 
 ### Ephemeral Identity (`useSessionIdentity`)
 The sync protocol can optionally generate an ephemeral Keystone Identity for the duration of the saga.
@@ -42,9 +51,9 @@ The sync protocol can optionally generate an ephemeral Keystone Identity for the
 
 ## Features
 *   **Symmetric Design**: No distinct "Client" or "Server" logic.
-*   **Smart Diff**: Efficient "Knowledge Vector" exchange to transfer only missing deltas.
-*   **Constants & Timelines**: Support for syncing both mutable histories and immutable stones.
-*   **Optimistic Concurrency**: (In Progress) Branch detection and merge strategies.
+*   **Smart Diff**: Efficient "Knowledge Vector" exchange to transfer only missing deltas (though some inefficiencies may exist early on).
+*   **Timelines && Constants**: Support for syncing both mutable histories and immutable constant ibgibs.
+*   **Optimistic Conflict Resolution**: (In Progress) Branch detection and merge strategies.
 
 ## Verification
 We rely on rigorous In-Memory Simulation (`InnerSpace`) to verify complex graph scenarios. See **[Verification](./docs/verification.md)** for the full status.

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

@@ -0,0 +1,4 @@
+export const GRAFT_INFO_ATOM = 'graft_info';
+export const GRAFT_INFO_REL8N_NAME = 'graftinfo';
+export const GRAFT_BASE_REL8N_NAME = 'graftbase';
+export const GRAFT_ORPHAN_REL8N_NAME = 'graftorphan';

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

@@ -113,8 +113,10 @@ export async function findLCA({
     return { lcaAddr, branchA, branchB };
 }
 
+import { graftTimelines, mergeTextLCS } from '../graft-info/graft-info-helpers.mjs';
+
 /**
- * Optimistically merges two divergent timelines by inspecting DNA.
+ * Optimistically grafts two divergent timelines by inspecting DNA and replaying transforms.
  */
 export async function mergeDivergentTimelines({
     tipA,
@@ -127,82 +129,21 @@ export async function mergeDivergentTimelines({
     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. 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.
-        },
+    // 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,
     });
 
-    // Ideally we'd modify the result to add 'past' link to tipB.
-    // But for now, let's just achieve data convergence.
-
     return result;
 }