@ibgib/web-gib 0.0.1

package/src/witness/live-proxy-ibgib/live-proxy-ibgib-one-file.mts

@@ -0,0 +1,321 @@
+import { extractErrorMsg, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { Ib, IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import { IbGib_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { GIB, IB, ROOT } from "@ibgib/ts-gib/dist/V1/constants.mjs";
+import { WitnessWithContextBase_V1 } from "@ibgib/core-gib/dist/witness/witness-with-context/witness-with-context-base-v1.mjs";
+import { IbGibTimelineUpdateInfo } from "@ibgib/core-gib/dist/common/other/other-types.mjs";
+import { ObservableWitness, } from "@ibgib/core-gib/dist/common/pubsub/observable/observable-types.mjs";
+import { newupSubject } from "@ibgib/core-gib/dist/common/pubsub/subject/subject-helper.mjs";
+import { SubjectWitness } from "@ibgib/core-gib/dist/common/pubsub/subject/subject-types.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../../constants.mjs";
+import { WitnessWithContextData_V1, WitnessWithContextRel8ns_V1 } from "@ibgib/core-gib/dist/witness/witness-with-context/witness-with-context-types.mjs";
+import { IbGibSpaceAny } from "@ibgib/core-gib/dist/witness/space/space-base-v1.mjs";
+import { getGlobalMetaspace_waitIfNeeded } from "../../helpers.web.mjs";
+import { isSpaceIb } from "@ibgib/core-gib/dist/witness/space/space-helper.mjs";
+import { SpaceId } from "@ibgib/core-gib/dist/witness/space/space-types.mjs";
+import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * Helper ibgib witness for backing ibgib component instances.
+ *
+ * This witness's job is not intrinsically do much of anything, rather, its
+ * focus is to keep up-to-date with changes to a context.
+ *
+ * So this particular witness does not need to care about its own state (its gib
+ * is actually just primitive "gib"). So no calls to loadNewerSelfIfAvailable
+ * should be necessary.
+ *
+ * ## how to use
+ *
+ * ATOW (04/2025) the idea is to have an ibgib component that you want to keep
+ * up-to-date. So you include a backing model proxy ibgib and subscribe to its
+ * events, e.g., {@link LiveProxyIbGib.contextUpdated$}, and then the component
+ * will update its visual elements.
+ *
+ * ## notes on driving intent of this class
+ *
+ * There is quite a bit of plumbing involved with updating ibgibs
+ * when updates are published to the metaspace. This involves subscribing
+ * to the ibgib timeline's latestObs observable on the metaspace, checking if
+ * there are actual new updates, as well as other things.
+ *
+ * Our components, however, since they are web components must descend from
+ * HTMLElement, so we can't descend from WitnessWithContextBase_V1 directly.
+ *
+ * So my hope is that this will be performant enough, and maintainable enough,
+ * to have this backing model for ibgib components.
+ *
+ */
+export class LiveProxyIbGib<TIbGib extends IbGib_V1 = IbGib_V1> extends WitnessWithContextBase_V1 {
+    protected lc: string = ``;
+
+    ib = this._currentWorkingContextIbGib ? this._currentWorkingContextIbGib.ib : IB;
+    gib = this._currentWorkingContextIbGib ? this._currentWorkingContextIbGib.gib : GIB;
+    data = this._currentWorkingContextIbGib ? this._currentWorkingContextIbGib.data : undefined;
+    rel8ns = this._currentWorkingContextIbGib ? this._currentWorkingContextIbGib.rel8ns : undefined;
+
+    protected override async loadNewerSelfIfAvailable(): Promise<void> {
+        const lc = `${this.lc}[${this.loadNewerSelfIfAvailable.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+            // doesn't look like this gets hit right now
+            console.warn(`${lc} does nothing in this class. I just have this warning here because I want to see if this gets executed. (W: genuuid)`)
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+    override async loadIbGibDto(dto: IbGib_V1<WitnessWithContextData_V1, WitnessWithContextRel8ns_V1>): Promise<void> {
+        const lc = `${this.lc}[${this.loadIbGibDto.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+            debugger; // does live proxy ibgib hit here?
+            console.warn(`${lc} does nothing in this class. I just have this warning here because I want to see if this gets executed. (W: genuuid)`)
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * not a "true" witness as I'm thinking right now so I'm not validating this
+     * proxy class. I am keeping the validateArg function though, as that seems
+     * good to me.
+     */
+    protected override async validateThis(): Promise<string[]> {
+        const lc = `${this.lc}[${this.validateThis.name}]`;
+        if (logalot) { console.log(`${lc} elided in this proxy class because this isn't a true witness atow (04/2025) (I: fd223814f169798d9f499d6e9cdc0325)`); }
+        return [];
+    }
+
+    get ibGib(): TIbGib | undefined {
+        return this._currentWorkingContextIbGib as TIbGib | undefined;
+    }
+
+    /**
+     * determines the local space in which this proxy ibgib resides.
+     *
+     * set this via passing in a space ibgib for the proxy to witness.
+     */
+    spaceId: SpaceId | undefined;
+
+    constructor(initialData?: any, initialRel8ns?: IbGibRel8ns_V1) {
+        super(initialData, initialRel8ns);
+    }
+
+    protected override async initialize(): Promise<void> {
+        const lc = `${this.lc}[${this.initialize.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 1bd72217a5f334effc63f8d51e7b2225)`); }
+            await super.initialize();
+
+            // init observables event streams
+            this._contextUpdated$ = await newupSubject();
+            this.contextUpdated$ = this._contextUpdated$.asObservable();
+
+            this._newContextChild$ = await newupSubject();
+            this.newContextChild$ = this._newContextChild$.asObservable();
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+
+    protected parseAddlMetadataString({ ib }: { ib: Ib; }): any {
+        const lc = `${this.lc}[${this.parseAddlMetadataString.name}]`;
+        console.warn(`${lc} not really implemented in this class atow (04/2025). (W: genuuid)`);
+        return {};
+    }
+
+    /**
+     * @internal
+     *
+     * The first context ibgib frame that this proxy is initialized with,
+     * namely, before any updates happen that produce newer ibgibs in the
+     * timelines. Those will update the {@link _currentWorkingContextIbGib}.
+     */
+    protected _initialContext: TIbGib | undefined;
+
+    /**
+     * implementation for witnessing. Basically, the first ibgib this proxy
+     * witnesses is its context, i.e., its ibgib.
+     *
+     * ## notes
+     *
+     * ### on "Context" with this Proxy
+     *
+     * "Context" is kinda funny in this way, but it's how I'm reusing existing
+     * plumbing for updating contexts.
+     *
+     * Said another way, usually a "context" is peripheral/ambient compared to
+     * the primary behavior of a witness with context. But in this use case as a
+     * proxy ibgib, "context" is just the actual ibgib.
+     */
+    protected async witnessImpl(arg: IbGib_V1<any, IbGibRel8ns_V1>): Promise<IbGib_V1<any, IbGibRel8ns_V1> | undefined> {
+        const lc = `${this.lc}[${this.witnessImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            if (isSpaceIb({ ib: arg.ib })) {
+                // we're setting the local space
+                if (!arg.data) { throw new Error(`arg has space ib but arg.data is falsy (E: b2af9226c067d5e72f117fa36e239525)`); }
+                const spaceId: SpaceId = arg.data.uuid as string;
+                this.spaceId = spaceId;
+                if (logalot) { console.log(`${lc} spaceId set to the ${spaceId} (I: 018724a5431ba421b71fad36924c5a25)`); }
+                // return a primitive string
+                return Factory_V1.primitive({ ib: `spaceId set to ${spaceId}` });
+            } else {
+                // we're wrapping an ibgib
+                if (!this._initialContext) {
+                    const space = await this.metaspace?.getLocalUserSpace({ localSpaceId: this.spaceId });
+                    await this.setWrappedIbGib({
+                        ibGib: arg,
+                        space,
+                    });
+                    // return ROOT => default action taken
+                    return ROOT;
+                } else {
+                    debugger; // error
+                    console.error(`${lc} (UNEXPECTED) context already initialized. returning early without doing anything. NOTE: This error was not thrown, only logged. (E: genuuid)`);
+                }
+            }
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    _contextUpdated$: SubjectWitness<TIbGib> | undefined;
+    /**
+     * similar to {@link newContextChild$}, but this is triggered when a NEW
+     * context ibgib is published via the metaspace (not its children).
+     *
+     * I believe this happens before the {@link newContextChild$} but don't
+     * quote me.
+     *
+     * ## notes
+     *
+     * * sometimes an ibgib is published on the timeline by the metaspace but it
+     *   is not actually new. So this swallows those old updates to essentially
+     *   be idempotent
+     *
+     * @see {@link _contextUpdated$}
+     * @see {@link newContextChild$}
+     */
+    contextUpdated$: ObservableWitness<TIbGib> | undefined;
+    /**
+     *
+     */
+    _newContextChild$: SubjectWitness<IbGib_V1> | undefined;
+    /**
+     * similar to {@link contextUpdated$}, but this happens when new _children_
+     * are added to the context ibgib, not just when the context ibgib itself is
+     * changed.
+     *
+     * This wraps {@link WitnessWithContextBase_V1.handleNewContextChild}
+     *
+     * @see {@link _newContextChild$}
+     * @see {@link contextUpdated$}
+     */
+    newContextChild$: ObservableWitness<IbGib_V1> | undefined;
+
+    protected async handleContextUpdate({ update }: { update: IbGibTimelineUpdateInfo; }): Promise<void> {
+        const lc = `${this.lc}[${this.handleContextUpdate.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: c262bcda065c086ffe9e3ac5899abe25)`); }
+
+            await super.handleContextUpdate({ update });
+            if (!this._contextUpdated$) { throw new Error(`(UNEXPECTED) this._contextUpdated$ falsy? (E: a184df090502bed9649f8df88bd4c125)`); }
+            await this._contextUpdated$.next(this._currentWorkingContextIbGib as TIbGib);
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    async setWrappedIbGib({
+        ibGib,
+        ibGibAddr,
+        space,
+    }: {
+        ibGib?: IbGib_V1,
+        ibGibAddr?: IbGibAddr,
+        space?: IbGibSpaceAny,
+    }): Promise<void> {
+        const lc = `${this.lc}[${this.setWrappedIbGib.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: a4b0acda259c121801aa701534320125)`); }
+            if (!this.metaspace) {
+                this.metaspace = await getGlobalMetaspace_waitIfNeeded();
+                // throw new Error(`(UNEXPECTED) this.metaspace falsy? (E: 60dc3b1eb082dfc266a33cd4cc96a525)`);
+            }
+
+            // get the ibgib by addr if necessary
+            // initialize the context with the ibgib
+            // NOTE: this.initializeContext says it has the ability to load from
+            // addr, but it doesn't and I'm too "lazy" right now to change that
+            // lib.
+
+            if (!ibGib) {
+                if (!ibGibAddr) { throw new Error(`(UNEXPECTED) both ibGib AND ibGibAddr falsy? (E: 6fac98ba2d4cfdec2b7ee974dec74625)`); }
+
+                space ??= await this.metaspace.getLocalUserSpace({ lock: false });
+                if (!space) { throw new Error(`(UNEXPECTED) space falsy? no space provided and couldn't get default local user space? (E: e14d1b7a6586f99453fc571396d4df25)`); }
+                const resGet = await this.metaspace.get({
+                    addrs: [ibGibAddr],
+                    space,
+                });
+
+                if (!resGet.success || resGet.ibGibs?.length !== 1) {
+                    throw new Error(`${lc} failed to get ibGib(?) (${ibGibAddr}). space.ib: ${space.ib} (E: b38f0a25d92e44c0aa5cc3b038a43c6c)`);
+                }
+                ibGib = resGet.ibGibs.at(0)!;
+            }
+
+            await this.initializeContext({
+                // arg: ibGib as TIbGib,
+                contextIbGib: ibGib as TIbGib,
+                // empty string for rel8nName avoids attempting to rel8 this
+                // witness to the context...sniff sniff
+                rel8nName: '',
+            });
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected override async handleNewContextChild({ newChild }: { newChild: IbGib_V1; }): Promise<void> {
+        const lc = `[${this.handleNewContextChild.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 7e9b6b7a4bb2726e9c717f230dfe1925)`); }
+            // console.error(`${lc} not really an error. newChild: ${pretty(newChild)}`);
+
+            if (!this._newContextChild$) { throw new Error(`(UNEXPECTED) this._contextUpdated$ falsy? (E: a184df090502bed9649f8df88bd4c125)`); }
+            await this._newContextChild$.next(newChild);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/witness/space/metaspace/metaspace-webspace/metaspace-webspace-helper.mts

@@ -0,0 +1,290 @@
+import { extractErrorMsg, getTimestamp, getUUID, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { getGib, isPrimitive } from "@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs";
+import { GIB } from "@ibgib/ts-gib/dist/V1/constants.mjs";
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import { getIbAndGib } from "@ibgib/ts-gib/dist/helper.mjs";
+import { SyncSagaInfo, SyncStatusIbGib } from "@ibgib/core-gib/dist/witness/space/outer-space/outer-space-types.mjs";
+import { SubscriptionWitness } from "@ibgib/core-gib/dist/common/pubsub/subscription/subscription-types.mjs";
+import { fnObs } from "@ibgib/core-gib/dist/common/pubsub/observer/observer-helper.mjs";
+import { ErrorIbGib_V1 } from "@ibgib/core-gib/dist/common/error/error-types.mjs";
+import { IbGibSpaceAny } from "@ibgib/core-gib/dist/witness/space/space-base-v1.mjs";
+import {
+    DtoToSpaceFunction, LocalSpaceFactoryFunction, MetaspaceService,
+} from "@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs";
+import { isSpaceIb, spaceNameIsValid } from "@ibgib/core-gib/dist/witness/space/space-helper.mjs";
+import {
+    IBGIB_BASE_DIR, IBGIB_BASE_SUBPATH, IBGIB_BIN_SUBPATH,
+    IBGIB_DNA_SUBPATH, IBGIB_ENCODING, IBGIB_IBGIBS_SUBPATH, IBGIB_META_SUBPATH
+} from "@ibgib/core-gib/dist/witness/space/filesystem-space/filesystem-constants.mjs";
+import {
+    DEFAULT_LOCAL_SPACE_DESCRIPTION, DEFAULT_LOCAL_SPACE_POLLING_INTERVAL_MS,
+    PERSIST_OPTS_AND_RESULTS_IBGIBS_DEFAULT
+} from "@ibgib/core-gib/dist/witness/space/space-constants.mjs";
+import { toDto } from "@ibgib/core-gib/dist/common/other/ibgib-helper.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../../../../constants.mjs";
+import { getFnPrompt } from "../../../../common/prompt-functions.web.mjs";
+import { WebFilesystemSpace_V1 } from "../../web-filesystem-space/web-filesystem-space-v1.mjs";
+import { WebFilesystemSpaceData_V1, WebFilesystemSpaceRel8ns_V1 } from "../../web-filesystem-space/web-filesystem-space-types.mjs";
+
+/**
+ * used in verbose logging (across all ibgib libs atow)
+ */
+const logalot = GLOBAL_LOG_A_LOT;
+
+export const fnCreateNewLocalSpace: LocalSpaceFactoryFunction = async ({
+    allowCancel,
+    spaceName,
+    logalot,
+}) => {
+    const lc = `[fnCreateNewLocalSpace]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: b05e12810c1d32269b0fa7e965ccfd24)`); }
+
+        if (spaceName && !spaceNameIsValid(spaceName)) {
+            throw new Error(`spaceName (${spaceName}) is invalid.  (E: c54aa952ee34102befe5f47681cdf624)`);
+            // throw because this is used in RCLI and automated testing...
+        }
+        if (!spaceName) {
+
+            const promptName: () => Promise<void> = async () => {
+                const fnPrompt = getFnPrompt();
+                const resName = await fnPrompt({
+                    title: 'greetings program', msg: `this website does not use cookies. it's driven by ibgib's innovative protocol, and all of YOUR data is stored in a "local space" on YOUR device. in browsers, this means in IndexedDB.
+
+so give your local space a name like 'phone_alice' or 'web_bob_foo', or leave blank to get a random name. then click ok.
+`
+                });
+
+                if (resName === '' && !allowCancel) {
+                    spaceName = 'space_' + (await getUUID()).slice(0, 10);
+                } else {
+                    if (resName && spaceNameIsValid(resName)) {
+                        spaceName = resName;
+                    }
+                }
+            };
+
+            // ...prompt for name
+            await promptName();
+
+            if (!spaceName) { return undefined; /* <<<< returns early */ }
+        }
+
+        // ...create in memory with defaults
+        const now = new Date();
+        const timestamp = getTimestamp(now);
+        const timestampMs = now.getMilliseconds();
+        const newLocalSpace = new WebFilesystemSpace_V1(/*initialData*/ {
+            version: '1',
+            uuid: await getUUID(),
+            isTjp: true,
+            timestamp,
+            timestampMs,
+            name: spaceName,
+            baseDir: IBGIB_BASE_DIR,
+            spaceSubPath: spaceName,
+            baseSubPath: IBGIB_BASE_SUBPATH,
+            binSubPath: IBGIB_BIN_SUBPATH,
+            dnaSubPath: IBGIB_DNA_SUBPATH,
+            ibgibsSubPath: IBGIB_IBGIBS_SUBPATH,
+            metaSubPath: IBGIB_META_SUBPATH,
+            encoding: IBGIB_ENCODING,
+            persistOptsAndResultIbGibs: PERSIST_OPTS_AND_RESULTS_IBGIBS_DEFAULT,
+            validateIbGibAddrsMatchIbGibs: true,
+            trace: false,
+            description: DEFAULT_LOCAL_SPACE_DESCRIPTION,
+            allowPrimitiveArgs: false,
+            catchAllErrors: true,
+            longPollingIntervalMs: DEFAULT_LOCAL_SPACE_POLLING_INTERVAL_MS,
+        } as WebFilesystemSpaceData_V1, /*initialRel8ns*/ undefined);
+        if (logalot) { console.log(`${lc} localSpace.ib: ${newLocalSpace.ib} (I: f57802654c5be84eb96d36d477425924)`); }
+        if (logalot) { console.log(`${lc} localSpace.gib: ${newLocalSpace.gib} (before sha256v1) (I: 4171271b7c1484e90205824a31067924)`); }
+        if (logalot) { console.log(`${lc} localSpace.data: ${pretty(newLocalSpace.data || 'falsy')} (I: 01221a1d7f6f19accf05b17534e3e624)`); }
+        if (logalot) { console.log(`${lc} localSpace.rel8ns: ${pretty(newLocalSpace.rel8ns || 'falsy')} (I: 750a7ec2b25b5d344dea900cf14ca524)`); }
+
+        // trying out with tjp, can't remember why didn't have it except for
+        // backwards compatability which i'm no longer shooting for (will be
+        // able to project old spaces to new ones i believe)
+        // newLocalSpace.gib = await getGib({ ibGib: newLocalSpace, hasTjp: false });
+        newLocalSpace.gib = await getGib({ ibGib: toDto({ ibGib: newLocalSpace }), hasTjp: true });
+
+        if (newLocalSpace.gib === GIB) { throw new Error(`localSpace.gib not updated correctly. (E: 277f8305ec3fd8dd4b023616c1fa0624)`); }
+        if (logalot) { console.log(`${lc} localSpace.gib: ${newLocalSpace.gib} (after sha256v1) (I: d3ab464fdb4500d95a50bf1e7c036524)`); }
+
+        return newLocalSpace as IbGibSpaceAny;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+export const fnDtoToSpace_webFilesystem: DtoToSpaceFunction = (spaceDto) => {
+    return Promise.resolve(
+        WebFilesystemSpace_V1.createFromDto(spaceDto as IbGib_V1<WebFilesystemSpaceData_V1, WebFilesystemSpaceRel8ns_V1>)
+    );
+}
+
+/**
+ * wrapper around metaspace.syncIbGibs
+ * @param param0
+ * @returns
+ */
+export async function doSync_awaitAllSagas({
+    addr,
+    metaspace,
+    localSpace,
+    syncSpaces,
+    sagaReporter,
+    verbose,
+}: {
+    /**
+     * the addr whose live dependency graph is going to be built and synced.
+     */
+    addr: IbGibAddr,
+    /**
+     * it's meta yo
+     */
+    metaspace: MetaspaceService,
+    /**
+     * the space which contains the syncSpace (proxy outer space).
+     */
+    localSpace: IbGibSpaceAny,
+    /**
+     * sync space witnesses (not just ibgib dtos)
+     */
+    syncSpaces: IbGibSpaceAny[],
+    sagaReporter: (msg: string, saga: SyncSagaInfo | null) => Promise<void>,
+    /**
+     * If true, will report more in {@link sagaReporter}
+     */
+    verbose?: boolean,
+}): Promise<SyncSagaInfo[] | undefined> {
+    const lc = `[${doSync_awaitAllSagas.name}]`;
+    try {
+        if (logalot || verbose) { console.log(`${lc} starting... (I: 78bf9e5bea88d9b3827bb991eeedc524)`); }
+        const { ib, gib } = getIbAndGib({ ibGibAddr: addr });
+
+        if (isPrimitive({ gib })) { throw new Error(`can't sync primitive ibgib (${addr}) (E: 915b331b00118b5f69e630ef5d2b8d24)`); }
+        if (isSpaceIb({ ib })) { throw new Error(`can't sync entire space ibgib (${addr}) (E: bd1b991e35a683df5a79c379c21d3924)`); }
+        if (syncSpaces.length === 0) { throw new Error(`syncSpaces required (E: 671b4f4adc6e009ed304419d662b2d24)`); }
+        if (syncSpaces.some(x => !x.witness)) { throw new Error(`(UNEXPECTED) syncSpaces.some(x => !x.witness)? sync spaces should all be witnesses (and have a witness function). these are not supposed to be just dtos (with ib, gib, data, rel8ns props). (E: 879c32b69856218f7eeafb89db491524)`); }
+
+        if (verbose) { await sagaReporter('getDependencyGraph starting... (I: 35cb6f89e87d7300b3be4088b4176a24)', null); }
+
+        const dependencyGraph = await metaspace.getDependencyGraph({
+            space: localSpace,
+            ibGibAddr: addr,
+            live: true,
+            msBetweenRetries: 1_000,
+        });
+
+        if (verbose) {
+            await sagaReporter('getDependencyGraph complete. (I: ec9aadd538ac3a61da3873c53852d324)', null);
+            await sagaReporter('syncIbGibs spinning off... (I: a15ddf897f8797848b350ad6a2067b24)', null);
+        }
+
+        const sagas = await metaspace.syncIbGibs({
+            dependencyGraphIbGibs: Object.values(dependencyGraph),
+            syncSpaceIbGibs: syncSpaces,
+            localSpace,
+        }) ?? [];
+        if (sagas.length === 0) { throw new Error(`(UNEXPECTED) metaspace.syncIbGibs returned undefined (no sagas)? (E: 4d7faeb9ed95fe4b162f2a1377928b24)`); }
+        if (verbose) {
+            await sagaReporter('syncIbGibs spin off complete. these are not yet done, it/they are just spun off and going. (I: a958a6b706c9b66933cb82ea7bbfcc24)', sagas.at(0) ?? null);
+        }
+
+        let sagaCount = sagas.length;
+        let sagaErrorCounter = 0;
+        /**
+         * using this during debugging...
+         */
+        const sagaErrorMsgs: string[] = [];
+        let sagaCompleteOrErrorCounter = 0;
+        let allSagasCompletePromise = new Promise<void>((resolve, reject) => {
+            const interval = setInterval(async () => {
+                if (sagaCompleteOrErrorCounter === sagaCount) {
+                    if (sagaErrorCounter > 0) {
+                        reject(`saga had errors: ${sagaErrorMsgs.join('|')} (E: c039232a158cd69669e233a84f9be924)`);
+                    }
+                    clearInterval(interval);
+                    resolve();
+                }
+            }, 500);
+        });
+
+        const fnIncCompleteOrError = async (saga: SyncSagaInfo) => {
+            const lcInner = `${lc}[fnIncCompleteOrError]`;
+            if (logalot || verbose) { console.log(`${lcInner} starting... (I: 1c41e7aaab13ecdf4f3608533f38b324)`); }
+            try {
+                sagaCompleteOrErrorCounter++;
+                let updateText: string;
+                if (sagaCompleteOrErrorCounter < sagaCount) {
+                    updateText = `saga (${saga.sagaId}) complete or errored. ONLY SOME (${sagaCompleteOrErrorCounter}/${sagaCount}) have completed or errored. still more to go...`;
+                } else if (sagaCompleteOrErrorCounter === sagaCount) {
+                    updateText = `saga (${saga.sagaId}) complete or errored. ALL ${sagaCount} sync sagas COMPLETE OR ERRORED.`;
+                } else {
+                    debugger; // unexpected error state. sagaCompleteOrErrorCounter > sagaCount
+                    updateText = `uhh, there is an error here. we have incremented sagaCompleteOrErrorCounter (${sagaCompleteOrErrorCounter}) to be greater than sagaCount (${sagaCount}) (E: b8e934cfce188f40a93cb90a462c7c24)`;
+                }
+                if (logalot || verbose) {
+                    console.log(`${lc} ${updateText} (I: 519a895d1a7ddc44cf8b4532cf3b6524)`);
+                    await sagaReporter(`${lcInner} ${updateText}`, saga);
+                }
+            } catch (error) {
+                console.error(`${lc} ${extractErrorMsg(error)}`);
+                throw error;
+            } finally {
+                if (logalot || verbose) { console.log(`${lc}[fnIncCompleteOrError] complete. (I: f2be67aa53e59ab2e5a7f89b26b4df24)`); }
+            }
+        };
+
+        for (let i = 0; i < sagas.length; i++) {
+            const saga = sagas[i];
+            let subscription: SubscriptionWitness = await saga.syncStatus$.subscribe(fnObs({
+                next: async (status: SyncStatusIbGib) => {
+                    if (logalot || verbose) {
+                        console.log(`${lc} console.dir(status)... (I: e786c4449ebf14be5b2d63a61d22c824)`);
+                        console.dir(status);
+                    } else {
+                        let statusCode = status.data?.statusCode;
+                        if (statusCode === "already_synced") {
+                            process.stdout.write('.');
+                        } else {
+                            console.log(statusCode);
+                        }
+                    }
+                },
+                complete: async () => {
+                    if (logalot || verbose) {
+                        console.log(`${lc}[saga complete] triggered for saga (${saga.spaceId}, ${saga.multiSpaceOpId}). (I: 999536aeb555ac9eaac88c98aee71224)`);
+                    }
+                    await fnIncCompleteOrError(saga);
+                    await subscription.unsubscribe();
+                },
+                error: async (err: string | Error | ErrorIbGib_V1) => {
+                    const errorMsg = extractErrorMsg(err);
+                    sagaErrorMsgs.push(errorMsg);
+                    if (errorMsg.includes('EAI_AGAIN')) {
+                        console.error(`this error may be because of no internet connection. ${errorMsg}`)
+                    }
+                    console.error(`${lc}[error] err: ${errorMsg} (E: 90b11d262194884ae8320ccbf7252124)`);
+                    sagaErrorCounter++;
+                    await fnIncCompleteOrError(saga);
+                    await subscription.unsubscribe();
+                    // sagaCompleteOrErrorCounter++;
+                }
+            }));
+        }
+        await allSagasCompletePromise;
+        return sagas;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot || verbose) { console.log(`${lc} complete.`); }
+    }
+}