@ibgib/core-gib 0.1.19 → 0.1.21

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

@@ -20,6 +20,8 @@ export async function getSyncSagaMessageIb({
             data.stage
         ].join(' ');
 
+        // console.log(`${lc} constructed ib: ${ib}`); // temporary debug
+
         return ib;
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -57,3 +59,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

@@ -47,25 +47,37 @@ export interface SyncSagaMessageAckData_V1 extends SyncSagaMessageData_V1 {
      * 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 {
     stage: typeof SyncStage.commit;
 }
 
-export interface SyncSagaMessageConflictData_V1 extends SyncSagaMessageData_V1 {
-    stage: typeof SyncStage.conflict;
-    conflictStrategy: SyncConflictStrategy;
-    isTerminal: boolean; // default true for V1
-    conflicts: {
-        tjp: string;
-        localAddr?: string;
-        remoteAddr?: string;
-        reason?: string;
-    }[];
-}

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: