@ibgib/core-gib 0.1.12 → 0.1.14

package/src/sync/sync-saga-coordinator.respec.mts

@@ -33,13 +33,13 @@ await respecfully(sir, 'SyncSagaCoordinator', async () => {
         const identitySecret = 'secret';
 
         // Execute Sync
-        await coordinator.sync({
-            source: sourceSpace,
-            dest: destSpace,
-            identity,
-            domainIbGibs: [], // Empty for test
-            identitySecret
-        });
+        // await coordinator.deprecated_sync({
+        //     source: sourceSpace,
+        //     dest: destSpace,
+        //     identity,
+        //     domainIbGibs: [], // Empty for test
+        //     identitySecret
+        // });
 
         // Verify Dest has received frames
         // We look for any ibgibs in the destSpace witness output

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

@@ -0,0 +1 @@
+export const SYNC_SAGA_MSG_ATOM = 'sync_sagamsg';

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

@@ -0,0 +1,59 @@
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { Ib } from "@ibgib/ts-gib/dist/types.mjs";
+import { SYNC_SAGA_MSG_ATOM } from "./sync-saga-message-constants.mjs";
+import { SyncSagaMessageData_V1, SyncSagaMessageIb_V1 } from "./sync-saga-message-types.mjs";
+
+/**
+ * Constructs the standard 'ib' string for a Sync Saga Message stone.
+ */
+export async function getSyncSagaMessageIb({
+    data,
+}: {
+    data: SyncSagaMessageData_V1,
+}): Promise<Ib> {
+    const lc = `[${getSyncSagaMessageIb.name}]`;
+    try {
+        // sync_saga_msg sagaId stage
+        const ib = [
+            SYNC_SAGA_MSG_ATOM,
+            data.sagaId,
+            data.stage
+        ].join(' ');
+
+        return ib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Parses a standard Sync Saga Message 'ib' string.
+ */
+export async function parseSyncSagaMessageIb({
+    ib,
+}: {
+    ib: Ib,
+}): Promise<SyncSagaMessageIb_V1> {
+    const lc = `[${parseSyncSagaMessageIb.name}]`;
+    try {
+        const parts = ib.split(' ');
+        if (parts.length !== 3) {
+            throw new Error(`Invalid sync saga message ib. Expected 3 parts [atom sagaId stage]. Got ${parts.length}. (E: 7abec847426bd8f41a475cafcc118826)`);
+        }
+        const [
+            atom,
+            sagaId,
+            stage
+        ] = parts;
+
+        if (atom !== SYNC_SAGA_MSG_ATOM) {
+            throw new Error(`Atom mismatch. Expected ${SYNC_SAGA_MSG_ATOM}. Got ${atom}. (E: 1b4ddf426ed87e474816ed48cedb8a26)`);
+        }
+
+        return { atom, sagaId, stage };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}

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

@@ -0,0 +1,53 @@
+import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { KeystoneIbGib_V1 } from "../../keystone/keystone-types.mjs";
+import { SyncStage } from "../sync-constants.mjs";
+import { SyncMode, SyncConflictStrategy, SyncInitData, SyncRequestData, SyncDeltaData, SyncCommitData } from "../sync-types.mjs";
+import { SYNC_SAGA_MSG_ATOM } from "./sync-saga-message-constants.mjs";
+
+export interface SyncSagaMessageIb_V1 {
+    atom: typeof SYNC_SAGA_MSG_ATOM;
+    sagaId: string;
+    stage: string;
+}
+
+export interface SyncSagaMessageData_V1 extends IbGibData_V1 {
+    /**
+     * Unique ID for the synchronization session (saga).
+     */
+    sagaId: string;
+
+    /**
+     * Current stage of the protocol.
+     */
+    stage: SyncStage;
+}
+
+export interface SyncSagaMessageRel8ns_V1 extends IbGibRel8ns_V1 {
+    // potentially link to previous message in chain if we wanted chain-of-stones?
+    // For now, stones are independent or linked by the saga frame.
+}
+
+export interface SyncSagaMessageIbGib_V1 extends IbGib_V1<SyncSagaMessageData_V1, SyncSagaMessageRel8ns_V1> { }
+
+// ===========================================================================
+// CONCRETE MESSAGE PAYLOADS (EXTENDING DATA)
+// ===========================================================================
+
+export interface SyncSagaMessageInitData_V1 extends SyncSagaMessageData_V1, SyncInitData {
+    stage: typeof SyncStage.init;
+}
+
+export interface SyncSagaMessageAckData_V1 extends SyncSagaMessageData_V1 {
+    stage: typeof SyncStage.ack;
+    deltaReqAddrs: string[];
+    pushOfferAddrs: string[];
+}
+
+export interface SyncSagaMessageDeltaData_V1 extends SyncSagaMessageData_V1, SyncDeltaData {
+    stage: typeof SyncStage.delta;
+    requests?: string[];
+}
+
+export interface SyncSagaMessageCommitData_V1 extends SyncSagaMessageData_V1, SyncCommitData {
+    stage: typeof SyncStage.commit;
+}

package/src/sync/sync-types.mts

@@ -1,6 +1,82 @@
 import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+
 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";
+
+
+// #region SyncMode
+export const SYNC_MODE_PUSH = 'push';
+export const SYNC_MODE_PULL = 'pull';
+export const SYNC_MODE_SYNC = 'sync';
+export type SyncMode =
+    | typeof SYNC_MODE_PUSH
+    | typeof SYNC_MODE_PULL
+    | typeof SYNC_MODE_SYNC;
+export const SyncMode = {
+    push: SYNC_MODE_PUSH,
+    pull: SYNC_MODE_PULL,
+    sync: SYNC_MODE_SYNC,
+} satisfies { [key in SyncMode]: SyncMode };
+export const SYNC_MODE_VALID_VALUES = Object.values(SyncMode);
+export function isValidSyncMode(mode: string): mode is SyncMode {
+    return SYNC_MODE_VALID_VALUES.includes(mode as SyncMode);
+}
+// #endregion SyncMode
+
+// #region SyncConflictStrategy
+export const SYNC_CONFLICT_STRATEGY_ABORT = 'abort';
+export const SYNC_CONFLICT_STRATEGY_OPTIMISTIC = 'optimistic';
+export const SYNC_CONFLICT_STRATEGY_MANUAL = 'manual';
+export type SyncConflictStrategy =
+    | typeof SYNC_CONFLICT_STRATEGY_ABORT
+    | typeof SYNC_CONFLICT_STRATEGY_OPTIMISTIC
+    | typeof SYNC_CONFLICT_STRATEGY_MANUAL;
+export const SyncConflictStrategy = {
+    abort: SYNC_CONFLICT_STRATEGY_ABORT,
+    optimistic: SYNC_CONFLICT_STRATEGY_OPTIMISTIC,
+    manual: SYNC_CONFLICT_STRATEGY_MANUAL,
+} satisfies { [key in SyncConflictStrategy]: SyncConflictStrategy };
+export const SYNC_CONFLICT_STRATEGY_VALID_VALUES = Object.values(SyncConflictStrategy);
+export function isValidSyncConflictStrategy(strategy: string): strategy is SyncConflictStrategy {
+    return SYNC_CONFLICT_STRATEGY_VALID_VALUES.includes(strategy as SyncConflictStrategy);
+}
+// #endregion SyncConflictStrategy
+
+export interface SyncOptions {
+    /**
+     * The ibgibs we wish to sync.
+     * 
+     * These should all exist in {@link source}
+     */
+    domainIbGibs: IbGib_V1[],
+    /**
+     * The space containing the data we want to send.
+     */
+    source: IbGibSpaceAny;
+    /**
+     * The space receiving the data.
+     */
+    dest: IbGibSpaceAny;
+    /**
+     * The metaspace context (for registering sync sagas locally).
+     */
+    metaspace: MetaspaceService;
+    /**
+     * The identity authorizing this sync.
+     */
+    identity: KeystoneIbGib_V1;
+    /**
+     * The secret for the identity (to sign the commit).
+     */
+    identitySecret: string;
+    /**
+     * How to handle conflicts when both Source and Dest have diverged on the same timeline.
+     * @default 'abort'
+     */
+    conflictStrategy?: SyncConflictStrategy;
+}
 
 // ===========================================================================
 // PROTOCOL PAYLOADS
@@ -28,7 +104,7 @@ export interface SyncInitData {
      * e.g. "push" (I have data for you) or "pull" (Give me data).
      * @default 'push'
      */
-    mode?: 'push' | 'pull';
+    mode?: SyncMode;
 }
 
 /**
@@ -77,7 +153,7 @@ export interface SyncCommitData {
 // IBGIB DATA STRUCTURES
 // ===========================================================================
 
-export interface SyncIbInfo_V1 {
+export interface SyncIb_V1 {
     atom: typeof SYNC_ATOM;
     uuid: string;
     stage: SyncStage;
@@ -106,7 +182,7 @@ export interface SyncData_V1 extends IbGibData_V1 {
     /**
      * Polymorphic payload based on stage.
      */
-    payload: SyncInitData | SyncRequestData | SyncDeltaData | SyncCommitData;
+    payload?: SyncInitData | SyncRequestData | SyncDeltaData | SyncCommitData;
 }
 
 export interface SyncRel8ns_V1 extends IbGibRel8ns_V1 {
@@ -118,3 +194,27 @@ export interface SyncRel8ns_V1 extends IbGibRel8ns_V1 {
 }
 
 export interface SyncIbGib_V1 extends IbGib_V1<SyncData_V1, SyncRel8ns_V1> { }
+
+/**
+ * Information returned when starting a Sync Saga.
+ * Allows the caller to subscribe to updates and await completion.
+ */
+import { SubjectWitness } from "../common/pubsub/subject/subject-types.mjs";
+import { SyncSagaContextIbGib_V1 } from "./sync-saga-context/sync-saga-context-types.mjs";
+
+export interface SyncSagaInfo {
+    /**
+     * The unique ID of the saga.
+     */
+    sagaId: string;
+    /**
+     * Stream of context updates happening during the saga.
+     * Subscribe to this to receive real-time progress.
+     */
+    updates$: SubjectWitness<SyncSagaContextIbGib_V1>;
+
+    /**
+     * Promise that resolves when the saga completes successfully.
+     */
+    done: Promise<void>;
+}

package/src/timeline/timeline-api.mts

@@ -36,6 +36,19 @@ export interface Rel8nInfo {
 }
 
 export interface CommonTimelineOptsSansSkipLock {
+    /**
+     * If true, dna will not be created when executing transforms. 
+     * 
+     * ## intent / driving use case
+     * 
+     * We want to use the timeline api in working with the new sync saga code. 
+     * However, we do not want dna, because the sync saga should not be merged
+     * and there should be no dynamic composition required from dna.
+     * 
+     * But the default for this api should be for dna to be created, so we add 
+     * this negative flag. 
+     */
+    noDna?: boolean,
     /**
      * space of spaces. Should be a singleton. @see {@link MetaspaceService}
      */
@@ -144,6 +157,7 @@ export async function appendToTimeline({
     metaspace,
     space,
     skipLock,
+    noDna,
 }: {
     timeline: IbGib_V1,
     /**
@@ -222,7 +236,7 @@ export async function appendToTimeline({
                 type: 'rel8', // assuming rel8 is the transform type
                 src: latestTimelineIbGibDto, // Use the latest as the source
                 rel8nsToAddByAddr,
-                dna: true,
+                dna: noDna ? false : true,
                 nCounter: true,
             });
             const newTimelineIbGib = resRel8.newIbGib;
@@ -550,6 +564,7 @@ export async function mut8Timeline<TData extends IbGibData_V1 = any>({
     space,
     skipLock,
     timelineIndexInfo,
+    noDna,
 }: {
     /**
      * timeline ibgib whose `data` we're mutating.
@@ -619,7 +634,7 @@ export async function mut8Timeline<TData extends IbGibData_V1 = any>({
             const resMut8 = await mut8({
                 ...mut8Opts,
                 src: latestTimelineIbGibDto,
-                dna: true,
+                dna: noDna ? false : true,
                 nCounter: true,
             }) as TransformResult<IbGib_V1<TData, any>>;
             const newTimelineIbGib = resMut8.newIbGib;
@@ -728,6 +743,7 @@ export async function createTimeline<TData extends IbGibData_V1 = IbGibData_V1>(
     ib,
     data,
     rel8ns,
+    noDna,
     parentIb,
     parentIbGib,
     metaspace,
@@ -790,9 +806,9 @@ export async function createTimeline<TData extends IbGibData_V1 = IbGibData_V1>(
             ib,
             data,
             rel8ns,
-            // these options are what make this a "timeline"
-            dna: true,
+            dna: noDna ? false : true,
             nCounter: true,
+            squash: noDna ? true : false,
             tjp: { timestamp: true, uuid: true },
         });
 

package/src/witness/space/inner-space/inner-space-v1.mts

@@ -1,4 +1,4 @@
-import { clone, extractErrorMsg, groupBy, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { clone, extractErrorMsg, getUUID, groupBy, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 import { getIbGibAddr, } from '@ibgib/ts-gib/dist/helper.mjs';
 import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
@@ -85,7 +85,8 @@ export class InnerSpace_V1<
                 }
                 this.data!.classname = InnerSpace_V1.name; // always set?
             }
-            if (!this.data.uuid) { throw new Error(`this.data.uuid is falsy. right now i'm assuming data.uuid is truthy. this is what i'm using atow (12/2024) (E: e531e3c812c22324e856cf219e337825)`); }
+            // if (!this.data.uuid) { throw new Error(`this.data.uuid is falsy. right now i'm assuming data.uuid is truthy. this is what i'm using atow (12/2024) (E: e531e3c812c22324e856cf219e337825)`); }
+            this.data.uuid ??= await getUUID();
 
             this.ib = getSpaceIb({ space: this, classname: this.data!.classname });
             this.gib = await getGib({ ibGib: this });