@ibgib/core-gib 0.1.18 → 0.1.20

package/src/sync/sync-saga-message/sync-saga-message-helpers.mts

@@ -57,3 +57,44 @@ export async function parseSyncSagaMessageIb({
         throw error;
     }
 }
+
+/**
+ * Helper to retrieve the Message Stone associated with a Saga Frame.
+ * 
+ * Saga Frames link to their Message Stone via the `sync-msg` relationship.
+ */
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { IbGibSpaceAny } from "../../witness/space/space-base-v1.mjs";
+import { getRel8dIbGibs } from "../../common/other/ibgib-helper.mjs";
+import { SYNC_MSG_REL8N_NAME } from "../sync-constants.mjs";
+
+export async function getSyncSagaMessageFromFrame({
+    frameIbGib,
+    space,
+}: {
+    frameIbGib: IbGib_V1,
+    space: IbGibSpaceAny,
+}): Promise<IbGib_V1<SyncSagaMessageData_V1>> {
+    const lc = `[${getSyncSagaMessageFromFrame.name}]`;
+    try {
+        const rel8d = await getRel8dIbGibs({
+            ibGib: frameIbGib,
+            rel8nNames: [SYNC_MSG_REL8N_NAME],
+            space
+        });
+        const msgs = rel8d[SYNC_MSG_REL8N_NAME];
+
+        if (!msgs || msgs.length === 0) {
+            throw new Error(`(UNEXPECTED) No sync message stone found found for frame: ${frameIbGib.ib} (E: 8a4b2c1d3e5f6a9b7c8d9e0f1a2b3c4d)`);
+        }
+
+        if (msgs.length > 1) {
+            throw new Error(`(UNEXPECTED) Multiple sync message stones found (${msgs.length}) for frame: ${frameIbGib.ib}. logic not currently equipped to handle multiple messages per frame. (E: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d)`);
+        }
+
+        return msgs[0] as IbGib_V1<SyncSagaMessageData_V1>;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}

package/src/sync/sync-saga-message/sync-saga-message-types.mts

@@ -42,11 +42,39 @@ export interface SyncSagaMessageAckData_V1 extends SyncSagaMessageData_V1 {
     stage: typeof SyncStage.ack;
     deltaReqAddrs: string[];
     pushOfferAddrs: string[];
+    /**
+     * Map of group keys (TJP or Constant Addr) to list of known addresses (Full History).
+     * Used by Sender to calculate differential payloads.
+     */
+    knowledgeVector?: { [groupKey: string]: string[] };
+    /**
+     * List of identified conflicts.
+     * 
+     * If present, the Sender should use the `timelineAddrs` (Receiver's history) 
+     * to compute the LCA and delta requirements for merging.
+     */
+    conflicts?: {
+        tjpAddr: string;
+        localAddr: string;
+        remoteAddr: string;
+        /**
+         * Full history of the timeline from the Receiver's perspective.
+         * Used by Sender to find LCA.
+         */
+        timelineAddrs: string[];
+        reason: string;
+        terminal: boolean;
+    }[];
 }
 
 export interface SyncSagaMessageDeltaData_V1 extends SyncSagaMessageData_V1, SyncDeltaData {
     stage: typeof SyncStage.delta;
     requests?: string[];
+    /**
+     * Flag indicating the sender has no further requests or payloads 
+     * and is ready to commit the transaction.
+     */
+    proposeCommit?: boolean;
 }
 
 export interface SyncSagaMessageCommitData_V1 extends SyncSagaMessageData_V1, SyncCommitData {

package/src/sync/sync-types.mts

@@ -4,6 +4,7 @@ import { KeystoneIbGib_V1, KeystoneProof } from "../keystone/keystone-types.mjs"
 import { SYNC_ATOM, SyncStage } from "./sync-constants.mjs";
 import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
 import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
+import { SyncPeerWitness } from "./sync-peer/sync-peer-types.mjs";
 
 
 // #region SyncMode
@@ -45,6 +46,10 @@ export function isValidSyncConflictStrategy(strategy: string): strategy is SyncC
 // #endregion SyncConflictStrategy
 
 export interface SyncOptions {
+    /**
+     * The peer we are syncing with.
+     */
+    peer: SyncPeerWitness;
     /**
      * The ibgibs we wish to sync.
      * 
@@ -54,11 +59,15 @@ export interface SyncOptions {
     /**
      * The space containing the data we want to send.
      */
-    source: IbGibSpaceAny;
+    source?: IbGibSpaceAny;
+    /**
+     * Alias for {@link source}. Used in some contexts.
+     */
+    localSpace?: IbGibSpaceAny;
     /**
      * The space receiving the data.
      */
-    dest: IbGibSpaceAny;
+    dest?: IbGibSpaceAny;
     /**
      * The metaspace context (for registering sync sagas locally).
      */
@@ -66,16 +75,22 @@ export interface SyncOptions {
     /**
      * The identity authorizing this sync.
      */
-    identity: KeystoneIbGib_V1;
+    identity?: KeystoneIbGib_V1;
     /**
      * The secret for the identity (to sign the commit).
      */
-    identitySecret: string;
+    identitySecret?: string;
     /**
      * How to handle conflicts when both Source and Dest have diverged on the same timeline.
      * @default 'abort'
      */
     conflictStrategy?: SyncConflictStrategy;
+    /**
+     * @deprecated Use `identity` instead if you have a specific identity.
+     * If true, creates an ephemeral session identity.
+     * @default true
+     */
+    useSessionIdentity?: boolean;
 }
 
 // ===========================================================================
@@ -168,6 +183,20 @@ export interface SyncData_V1 extends IbGibData_V1 {
      */
     uuid: string;
 
+    /**
+     * Optional verification metadata (e.g. success count).
+     */
+    successCount?: number;
+    /**
+     * If failed, the reasons why.
+     */
+    errors?: string[];
+
+    /**
+     * Strategy used for resolving conflicts in this saga.
+     */
+    conflictStrategy?: SyncConflictStrategy;
+
     /**
      * Optional absolute timestamp (Unix ms) after which this frame should be considered void.
      * Useful for:

package/tmp.md

@@ -1,375 +1,3 @@
-/**
- * @module sync-innerspace-complex.respec
- *
- * Verifies Complex Sync Scenarios using InnerSpace.
- */
+Clarifying Merge Context
 
-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 { getDependencyGraph } from '../common/other/graph-helper.mjs';
-
-import { SyncSagaCoordinator } from './sync-saga-coordinator.mjs';
-import { putInSpace, 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';
-
-const logalot = true;
-const lc = `[sync-innerspace-complex.respec]`;
-
-await respecfully(sir, `Sync InnerSpaces (Complex)`, async () => {
-
-    let metaspace: Metaspace_Innerspace;
-    let sourceSpace: InnerSpace_V1;
-    let destSpace: InnerSpace_V1;
-
-    await respecfully(sir, `Multiple Timelines (Push Source -> Dest)`, 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 Source Data (Multiple Independent Timelines)
-        console.log(`${lc} Creating data in Source...`);
-
-        // Timeline A
-        const rootA = await createTimelineRootHelper({
-            ib: 'timeline_root_A',
-            data: { type: 'root', label: 'A' },
-            space: sourceSpace,
-        });
-        const childA = await mut8Timeline({
-            timeline: rootA,
-            mut8Opts: { dataToAddOrPatch: { type: 'child', label: 'A1' } },
-            metaspace,
-            space: sourceSpace,
-        });
-        const addrA = getIbGibAddr({ ibGib: childA });
-
-        // Timeline B
-        const rootB = await createTimelineRootHelper({
-            ib: 'timeline_root_B',
-            data: { type: 'root', label: 'B' },
-            space: sourceSpace,
-        });
-        // B has deeper history
-        const childB1 = await mut8Timeline({
-            timeline: rootB,
-            mut8Opts: { dataToAddOrPatch: { type: 'child', label: 'B1' } },
-            metaspace,
-            space: sourceSpace,
-        });
-        const childB2 = await mut8Timeline({
-            timeline: childB1,
-            mut8Opts: { dataToAddOrPatch: { type: 'child', label: 'B2' } },
-            metaspace,
-            space: sourceSpace,
-        });
-        const addrB = getIbGibAddr({ ibGib: childB2 });
-
-        // 3. Setup Coordinators & Peer
-        const mockKeystone = await getTestKeystoneServiceHelper();
-        const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
-        const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
-
-        const peer = new SyncPeerInnerspace_V1({
-            senderSpace: sourceSpace,
-            receiverSpace: destSpace,
-            receiverCoordinator: receiverCoordinator,
-            receiverMetaspace: metaspace,
-        });
-
-        // 4. Run Sync (Push Both)
-        console.log(`${lc} Running Sync...`);
-        const resSync = await senderCoordinator.sync({
-            peer: peer,
-            localSpace: sourceSpace,
-            metaspace: metaspace,
-            domainIbGibs: [childA, childB2], // Sync both tips
-            useSessionIdentity: false,
-        });
-
-        await resSync.done;
-        // await delay(100); // Wait for flush?
-
-        // 5. Verify Dest
-        console.log(`${lc} Verifying Destination...`);
-
-        await ifWeMight(sir, `verify timelines present`, async () => {
-            // Verify A
-            const getA = await getFromSpace({ space: destSpace, addr: addrA });
-            iReckon(sir, getA.success).asTo('Timeline A present').isGonnaBeTrue();
-            iReckon(sir, getA.ibGibs?.[0]?.data?.label).asTo('Label A match').isGonnaBe('A1');
-
-            // Verify B
-            const getB = await getFromSpace({ space: destSpace, addr: addrB });
-            iReckon(sir, getB.success).asTo('Timeline B present').isGonnaBeTrue();
-            iReckon(sir, getB.ibGibs?.[0]?.data?.label).asTo('Label B match').isGonnaBe('B2');
-        });
-
-    });
-
-    interface TestData {
-        type: string;
-        label?: string;
-        uuid?: string;
-        n?: number;
-    }
-
-    await respecfully(sir, `Deep Updates (Push Source -> Dest)`, 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 Source Data (Deep History)
-        console.log(`${lc} Creating deep data in Source...`);
-
-        // Root -> Comment (Child) -> Edit Comment (Child v2)
-        const root = await createTimelineRootHelper<TestData>({
-            ib: 'timeline_root_deep',
-            data: { type: 'root', label: 'Root' },
-            space: sourceSpace,
-        });
-
-        // n=1
-        const commentV1 = await mut8Timeline<TestData>({
-            timeline: root,
-            mut8Opts: { dataToAddOrPatch: { type: 'comment', label: 'Hello World' } },
-            metaspace,
-            space: sourceSpace,
-        });
-
-        // n=2 (Edit)
-        const commentV2 = await mut8Timeline<TestData>({
-            timeline: commentV1,
-            mut8Opts: { dataToAddOrPatch: { type: 'comment', label: 'Hello Sync' } },
-            metaspace,
-            space: sourceSpace,
-        });
-        const addrV2 = getIbGibAddr({ ibGib: commentV2 });
-
-        // 3. Setup
-        const mockKeystone = await getTestKeystoneServiceHelper();
-        const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
-        const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
-
-        const peer = new SyncPeerInnerspace_V1({
-            senderSpace: sourceSpace,
-            receiverSpace: destSpace,
-            receiverCoordinator: receiverCoordinator,
-            receiverMetaspace: metaspace,
-        });
-
-        // 4. Run Sync
-        console.log(`${lc} Running Sync...`);
-        // Debug Source Graph
-        const sourceGraph = await getDependencyGraph({ ibGib: commentV2, space: sourceSpace });
-        console.log(`${lc} Source Graph count: ${sourceGraph ? Object.keys(sourceGraph).length : 'null'}`);
-
-        const resSync = await senderCoordinator.sync({
-            peer: peer,
-            localSpace: sourceSpace,
-            metaspace: metaspace,
-            domainIbGibs: [commentV2], // Sync the TIP
-            useSessionIdentity: false,
-        });
-
-        await resSync.done;
-
-        // 5. Verify Dest
-        console.log(`${lc} Verifying Destination...`);
-
-        await ifWeMight(sir, `verify deep timeline present`, async () => {
-            // Verify Tip (V2)
-            const getV2 = await getFromSpace({ space: destSpace, addr: addrV2 });
-            iReckon(sir, getV2.success).asTo('Tip V2 present').isGonnaBeTrue();
-            const v2IbGib = getV2.ibGibs![0];
-            iReckon(sir, v2IbGib.data!.label).asTo('Label V2 match').isGonnaBe('Hello Sync');
-            // iReckon(sir, v2IbGib.data!.n).asTo('n=2').isGonnaBe(2); // Relaxing n check for now
-
-            // Verify Past Frame (V1) availability
-            // Sync should transfer dependencies (past frames)
-            // Rel8ns are accretive, so we check the LAST one.
-            const pastAddr = v2IbGib.rel8ns?.past?.at(-1);
-            if (pastAddr) {
-                const getV1 = await getFromSpace({ space: destSpace, addr: pastAddr });
-                iReckon(sir, getV1.success).asTo('Past Frame (V1) present').isGonnaBeTrue();
-                iReckon(sir, getV1.ibGibs?.[0]?.data?.label).asTo('Label V1 match').isGonnaBe('Hello World');
-            } else {
-                iReckon(sir, false).asTo('Past relation present').isGonnaBeTrue();
-            }
-
-            // Verify Full Graph Integrity (DNA, Roots)
-            const graph = await getDependencyGraph({ ibGib: v2IbGib, space: destSpace });
-            // const debugGraph = ... (removed)
-
-            iReckon(sir, !!graph).asTo('Dependency Graph resolvable in Dest').isGonnaBeTrue();
-            // Should contain Root, V1, V2
-            // We can check counts or specific existence.
-            iReckon(sir, Object.keys(graph!).length > 2).asTo('Graph size > 2').isGonnaBeTrue();
-        });
-    });
-
-    await respecfully(sir, `Dest Ahead (Remote Newer)`, async () => {
-        // 1. Setup Spaces
-        metaspace = new Metaspace_Innerspace(undefined);
-        await metaspace.initialize({
-            getFnAlert: () => async ({ title, msg }) => { },
-            getFnPrompt: () => async ({ title, msg }) => { return ''; },
-            getFnPromptPassword: () => async (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 Data
-        // Root -> V1 (Shared) -> V2 (Dest has New)
-        // Source only has V1.
-
-        const root = await createTimelineRootHelper<TestData>({
-            ib: 'timeline_root_ff',
-            data: { type: 'root', label: 'Root' },
-            space: sourceSpace,
-        });
-
-        // V1 (Both have it, but we create in source and copy to dest)
-        const v1 = await mut8Timeline<TestData>({
-            timeline: root,
-            mut8Opts: { dataToAddOrPatch: { type: 'comment', label: 'V1' } },
-            metaspace,
-            space: sourceSpace,
-        });
-
-        // Transfer Root & V1 to Dest
-        await putInSpace({ space: destSpace, ibGibs: [root, v1] }); // Naive seeding
-
-        // V2 (Created in Dest ONLY)
-        const v2 = await mut8Timeline<TestData>({
-            timeline: v1, // v1 is in memory, linked to source, but we want to Mutate IN DEST SPACE
-            mut8Opts: { dataToAddOrPatch: { type: 'comment', label: 'V2' } },
-            metaspace,
-            space: destSpace, // Mutate in Dest
-        });
-        const addrV2 = getIbGibAddr({ ibGib: v2 });
-
-        await ifWe(sir, 'verify setup', async () => {
-            // Ensure V2 is ONLY in Dest (it is, per `space: destSpace`)
-            // Ensure Source does NOT have V2
-            const checkV2InSource = await getFromSpace({ space: sourceSpace, addr: addrV2 });
-            iReckon(sir, checkV2InSource.success && !!checkV2InSource.ibGibs?.length).asTo('Source has V2').isGonnaBeFalse();
-        });
-
-        // 3. Setup Sync
-        const mockKeystone = await getTestKeystoneServiceHelper();
-        const senderCoordinator = new SyncSagaCoordinator(mockKeystone);
-        const receiverCoordinator = new SyncSagaCoordinator(mockKeystone);
-
-        const peer = new SyncPeerInnerspace_V1({
-            senderSpace: sourceSpace,
-            receiverSpace: destSpace,
-            receiverCoordinator: receiverCoordinator,
-            receiverMetaspace: metaspace,
-        });
-
-        // 4. Run Sync (Source Pushes V1)
-        console.log(`${lc} Running Sync...`);
-        const resSync = await senderCoordinator.sync({
-            peer: peer,
-            localSpace: sourceSpace,
-            metaspace: metaspace,
-            domainIbGibs: [v1], // Source tries to push V1
-            useSessionIdentity: false,
-        });
-
-        await resSync.done;
-
-        // 5. Verify Dest (Should still have V2 as latest)
-        console.log(`${lc} Verifying Destination...`);
-
-        await ifWeMight(sir, `verify dest stays ahead`, async () => {
-            // Verify Tip (V2)
-            const getV2 = await getFromSpace({ space: destSpace, addr: addrV2 });
-            iReckon(sir, getV2.success).asTo('V2 still present in Dest').isGonnaBeTrue();
-
-            // Verify V2 points to V1
-            const v2IbGib = getV2.ibGibs![0];
-            const pastAddr = v2IbGib.rel8ns?.past?.at(-1);
-            iReckon(sir, pastAddr === getIbGibAddr({ ibGib: v1 })).asTo('V2 points to V1').isGonnaBeTrue();
-        });
-
-    });
-
-});
+I'm now integrating merge context into handleDeltaFrame. It's crucial that this function knows the history of conflicts. I'm focusing on deriving state from the sagaIbGib and arguments, as the coordinator is mostly stateless. I'm thinking of checking for conflicts in the Ack within the saga history. If conflicts existed, I can then check for available merge data. This will involve inspecting delta changes to determine merge necessity, and if required, triggering merge based on existing conflicts. I'll add the necessary type updates accordingly.