@ibgib/core-gib 0.1.10 → 0.1.12

package/src/agent-helpers.mts

@@ -6,47 +6,132 @@
  * actions for creating and modifying data.
  */
 
+import { extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { IbGib_V1, IbGibRel8ns_V1, IbGibData_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
-import { IbGibAddr, Ib } from '@ibgib/ts-gib/dist/types.mjs';
+
+import { GLOBAL_LOG_A_LOT } from './core-constants.mjs';
 import { KeystoneService_V1 } from './keystone/keystone-service-v1.mjs';
 import { IbGibSpaceAny } from './witness/space/space-base-v1.mjs';
+import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { createTimeline } from './timeline/timeline-api.mjs';
+import { persistTransformResult, registerNewIbGib } from './witness/space/space-helper.mjs';
+import { MetaspaceService } from './witness/space/metaspace/metaspace-types.mjs';
+import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
 
 /**
  * Creates a "Stone" ibGib - an immutable, primitive-like data record with no history/timeline.
  * Useful for static data, configurations, or standalone records.
  */
-export async function createStoneHelper<TData = any>(opts: {
+export async function createStoneHelper<TData extends IbGibData_V1 = any>({
+    ib,
+    data,
+    rel8ns,
+    uuid,
+    noTimestamp,
+}: {
     ib: string;
     data?: TData;
     rel8ns?: IbGibRel8ns_V1;
     uuid?: boolean; // If true, generates a UUID in data
+    noTimestamp?: boolean;
 }): Promise<IbGib_V1<TData>> {
-    throw new Error("Not implemented yet. Agent waiting for user implementation.");
+    const lc = `[${createStoneHelper.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: e4b15ee74de22ec9a917c578adc83425)`); }
+
+        if (!ib) { throw new Error(`ib required (E: 3d5df8fd5b880e0e0dcedd37dbc3f825)`); }
+
+        // the parent primitive ib is almost always the atom of the ib.
+        const atom = ib.split(' ').at(0)!;
+
+        if (uuid) {
+            if (!data) { data = {} as TData; }
+            data.uuid = await getUUID();
+        }
+
+        const stone = await Factory_V1.stone({
+            parentPrimitiveIb: atom,
+            ib,
+            data,
+            rel8ns,
+            uuid,
+        });
+
+        return stone;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
 }
 
 /**
  * Creates a new "Living" Timeline Root.
  * This is the starting point for any mutable data structure (a file, a user profile, a post).
  */
-export async function createTimelineRootHelper<TData = any>(opts: {
+export async function createTimelineRootHelper<TData extends IbGibData_V1 = any>({
+    ib,
+    data,
+    space,
+}: {
     ib: string;     // e.g. "comment" or "task"
     data?: TData;   // Initial data
     space: IbGibSpaceAny; // Where to persist this new root
 }): Promise<IbGib_V1<TData>> {
-    throw new Error("Not implemented yet. Agent waiting for user implementation.");
-}
+    const lc = `[${createTimelineRootHelper.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 8f50a8cf0268742048f7c188feb5a825)`); }
 
-/**
- * Forks an existing timeline to create a new version (a child).
- * Used for updating data, adding a comment to a thread (if threading via timeline), etc.
- */
-export async function forkTimelineHelper<TData = any>(opts: {
-    timeline: IbGib_V1<TData>; // The current tip of the timeline
-    dataToAddOrPatch?: Partial<TData>;
-    rel8nsToAdd?: IbGibRel8ns_V1; // e.g. linking to another ibGib
-    space: IbGibSpaceAny;
-}): Promise<IbGib_V1<TData>> {
-    throw new Error("Not implemented yet. Agent waiting for user implementation.");
+        // const resTimeline = await createTimeline({
+        //     ib,
+        //     data,
+        //     rel8ns: undefined,
+        //     metaspace, space
+        // });
+        // const timeline = resTimeline.newIbGib;
+
+        // return timeline;
+
+        // Determine the parent to fork based on the provided options.
+        const atom = ib.split(' ').at(0)!;
+        const parentIbGib = Factory_V1.primitive({ ib: atom });
+
+        const resNew = await Factory_V1.firstGen<TData>({
+            parentIbGib,
+            ib,
+            data,
+            rel8ns: undefined,
+            // these options are what make this a "timeline"
+            dna: true,
+            nCounter: true,
+            tjp: { timestamp: true, uuid: true },
+        });
+
+        // Persist the new timeline and its DNA to the designated space.
+        await persistTransformResult({ resTransform: resNew, space });
+        await registerNewIbGib({
+            ibGib: resNew.newIbGib,
+            space,
+            /**
+             * We don't need to broadcast here because it's a new, independent
+             * timeline, so there are no listeners yet.
+             */
+            fnBroadcast: undefined,
+        });
+
+        // We don't need to lock here because it's a new, independent timeline,
+        // so there are no concurrency concerns yet.
+
+        return resNew.newIbGib as IbGib_V1<TData>;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
 }
 
 /**
@@ -54,5 +139,21 @@ export async function forkTimelineHelper<TData = any>(opts: {
  * This mocks the identity and signing logic needed for Sync operations.
  */
 export async function getTestKeystoneServiceHelper(): Promise<KeystoneService_V1> {
-    throw new Error("Not implemented yet. Agent waiting for user implementation.");
+    class MockKeystoneService extends KeystoneService_V1 {
+        async getIdentity(): Promise<any> {
+            // Return a dummy identity
+            // We use the Factory directly here to just get *something* that looks like an ibgib
+            const res = await Factory_V1.firstGen({
+                parentIbGib: Factory_V1.primitive({ ib: 'identity' }),
+                ib: 'identity',
+                data: { uuid: await getUUID() },
+                dna: true,
+            });
+            return res.newIbGib;
+        }
+        // Implement other methods as no-ops or simple mocks
+        async sign(args: any): Promise<any> { return args.latestKeystone; /* minimal mock */ }
+        async verify(args: any): Promise<any> { return []; /* no errors */ }
+    }
+    return new MockKeystoneService() as unknown as KeystoneService_V1;
 }

package/src/sync/sync-innerspace.respec.mts

@@ -0,0 +1,289 @@
+/**
+ * @module sync-innerspace.respec
+ *
+ * Verifies SyncSagaCoordinator using InnerSpace (in-memory/local) spaces.
+ * This avoids disk I/O issues and focuses on the synchronization logic.
+ */
+
+import {
+    respecfully, lastOfAll, ifWe, iReckon,
+    ifWeMight
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const maam = `[${import.meta.url}]`, sir = maam;
+
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/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 { createStoneHelper, createTimelineRootHelper, getTestKeystoneServiceHelper } from '../agent-helpers.mjs';
+import { mut8Timeline, appendToTimeline } from '../timeline/timeline-api.mjs';
+import { getDependencyGraph } from '../common/other/graph-helper.mjs';
+
+const logalot = true;
+const lc = `[sync-innerspace.respec]`;
+
+await respecfully(sir, `Sync InnerSpaces`, async () => {
+
+    let metaspace: Metaspace_Innerspace;
+    let sourceSpace: InnerSpace_V1;
+    let destSpace: InnerSpace_V1;
+
+    // Setup before each test? Or once?
+    // For now, let's just do it inside the test block to be safe/simple.
+
+    await ifWe(sir, `Basic Push Sync (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; },
+        });
+
+        // Create two distinct inner spaces manually or via metaspace if supported
+        // Metaspace_Innerspace typically manages one local user space, but we can instantiate InnerSpace_V1 directly.
+        sourceSpace = new InnerSpace_V1({ name: 'source', uuid: 'source_uuid' } as any);
+        await (sourceSpace as any).initialize();
+
+        destSpace = new InnerSpace_V1({ name: 'dest', uuid: 'dest_uuid' } as any);
+        await (destSpace as any).initialize();
+
+        // 2. Seed Source Data
+
+        // 2.1 Create a "Stone"
+        console.log(`${lc} Creating Stone...`);
+        const stone = await createStoneHelper({
+            ib: 'stone_data',
+            data: { some: 'data' },
+        });
+        const stoneAddr = getIbGibAddr({ ibGib: stone });
+        await putInSpace({ space: sourceSpace, ibGibs: [stone] });
+
+        // 2.2 Create a "Living" Timeline (Root)
+        console.log(`${lc} Creating Timeline Root...`);
+        const root = await createTimelineRootHelper({
+            ib: 'timeline_root',
+            data: { type: 'root', n: 0 },
+            space: sourceSpace,
+        });
+        const rootAddr = getIbGibAddr({ ibGib: root });
+
+        // 2.3 Evolve Timeline (Root -> Child)
+        // using mut8Timeline to simulate evolution
+        console.log(`${lc} Evolving Timeline...`);
+        const child = await mut8Timeline({
+            timeline: root,
+            mut8Opts: {
+                dataToAddOrPatch: { type: 'child', n: 1 }
+            },
+            metaspace,
+            space: sourceSpace,
+            // We use skipLock=true for simplicity in single-threaded test setup if locking is complex,
+            // but timeline-api handles locking. Let's try default first.
+            // Actually InnerSpace locking might be no-op or simple.
+        });
+        const childAddr = getIbGibAddr({ ibGib: child });
+
+        // 2.4 Rel8 Child to Stone (Dependency)
+        console.log(`${lc} Linking Child to Stone...`);
+        const childWithRel = await appendToTimeline({
+            timeline: child,
+            rel8nInfos: [{
+                rel8nName: 'linked_stone',
+                ibGibs: [stone]
+            }],
+            metaspace,
+            space: sourceSpace,
+        });
+        const childWithRelAddr = getIbGibAddr({ ibGib: childWithRel });
+
+        // 3. Setup Sync Coordinator
+        console.log(`${lc} Setting up Coordinator...`);
+        const mockKeystone = await getTestKeystoneServiceHelper();
+        const identity = await (mockKeystone as any).getIdentity();
+        const coordinator = new SyncSagaCoordinator(mockKeystone);
+
+        // 4. Run Sync
+        console.log(`${lc} Running Sync...`);
+        const syncRes = await coordinator.sync({
+            source: sourceSpace,
+            dest: destSpace,
+            domainIbGibs: [childWithRel], // Sync starting from the tip
+            identity
+        });
+
+        // 5. Verify Dest (Full Dependency Graph)
+        console.log(`${lc} Verifying Destination (Full Graph)...`);
+
+        // We expect the graph to contain: 
+        // 1. childWithRel
+        // 2. child (past of childWithRel)
+        // 3. root (ancestor of child, past of child)
+        // 4. stone (linked to childWithRel)
+        // 5. primitives (timeline_root, child, stone_data, identity, fork, mut8, rel8, root^gib, etc.)
+
+        // Let's get the graph from the source first to know what to expect (ground truth)
+        const sourceGraph = await getDependencyGraph({
+            ibGibs: [childWithRel],
+            space: sourceSpace,
+        });
+        const sourceAddrs = Object.keys(sourceGraph);
+        console.log(`${lc} Source Graph Size: ${sourceAddrs.length}`);
+
+        // Now get the graph from the destination
+        const destGraph = await getDependencyGraph({
+            ibGibs: [childWithRel],
+            space: destSpace,
+        });
+        const destAddrs = Object.keys(destGraph);
+        console.log(`${lc} Dest Graph Size: ${destAddrs.length}`);
+
+        // Assert
+        iReckon(sir, destAddrs.length).asTo('dest graph size').isGonnaBe(sourceAddrs.length);
+
+        for (const addr of sourceAddrs) {
+            const inDest = !!destGraph[addr];
+            if (!inDest) {
+                console.error(`${lc} Missing in dest: ${addr}`);
+            }
+            iReckon(sir, inDest).asTo(`addr present in dest: ${addr}`).isGonnaBeTrue();
+        }
+
+        console.log(`${lc} Verified Full Dependency Graph synced.`);
+    });
+
+    await ifWe(sir, `Idempotency (No-op if already synced)`, async () => {
+        // 1. Setup Spaces
+        const 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; },
+        });
+
+        const sourceSpace = new InnerSpace_V1({ name: 'source_idem', uuid: 'source_idem_uuid' } as any);
+        await (sourceSpace as any).initialize();
+
+        const destSpace = new InnerSpace_V1({ name: 'dest_idem', uuid: 'dest_idem_uuid' } as any);
+        await (destSpace as any).initialize();
+
+        // 2. Seed Source and Sync ONCE
+        const root = await createTimelineRootHelper({
+            ib: 'timeline_root',
+            data: { type: 'root', n: 0 },
+            space: sourceSpace,
+        });
+
+        const mockKeystone = await getTestKeystoneServiceHelper();
+        const identity = await (mockKeystone as any).getIdentity();
+        const coordinator = new SyncSagaCoordinator(mockKeystone);
+
+        console.log(`${lc} Running First Sync...`);
+        await coordinator.sync({
+            source: sourceSpace,
+            dest: destSpace,
+            domainIbGibs: [root],
+            identity
+        });
+
+        // Verify Initial State
+        const rootAddr = getIbGibAddr({ ibGib: root });
+        const getRoot1 = await getFromSpace({ space: destSpace, addr: rootAddr });
+        iReckon(sir, getRoot1.success).asTo('First Sync success').isGonnaBeTrue();
+
+        // 3. Run Sync AGAIN (Should be No-op)
+        console.log(`${lc} Running Second Sync...`);
+        await coordinator.sync({
+            source: sourceSpace,
+            dest: destSpace,
+            domainIbGibs: [root],
+            identity
+        });
+
+        // 4. Verify State Unchanged / Still Valid
+        const getRoot2 = await getFromSpace({ space: destSpace, addr: rootAddr });
+        iReckon(sir, getRoot2.success).asTo('Second Sync success').isGonnaBeTrue();
+
+        // Ensure no duplication or errors in destination (checking count in dependency graph might be good proxy?)
+        const destGraph = await getDependencyGraph({
+            ibGibs: [root],
+            space: destSpace,
+        });
+        iReckon(sir, Object.keys(destGraph).length).asTo('Dest Graph Size unchanged').isGonnaBe(Object.keys(destGraph).length); // Trivial assertion, mostly checking for no throw
+
+        console.log(`${lc} Verified Idempotency.`);
+    });
+
+    await ifWeMight(sir, `Dest Ahead (Pull/Fast-Backward)`, async () => {
+        // 1. Setup Spaces
+        const 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; },
+        });
+
+        const sourceSpace = new InnerSpace_V1({ name: 'source_pull', uuid: 'source_pull_uuid' } as any);
+        await (sourceSpace as any).initialize();
+
+        const destSpace = new InnerSpace_V1({ name: 'dest_pull', uuid: 'dest_pull_uuid' } as any);
+        await (destSpace as any).initialize();
+
+        // 2. Setup Initial Shared State
+        // Create root in Source, Sync to Dest
+        console.log(`${lc} Seeding initial shared state...`);
+        const root = await createTimelineRootHelper({
+            ib: 'timeline_pull',
+            data: { type: 'root', n: 0, state: 'initial' },
+            space: sourceSpace,
+        });
+        const rootAddr = getIbGibAddr({ ibGib: root });
+
+        const mockKeystone = await getTestKeystoneServiceHelper();
+        const identity = await (mockKeystone as any).getIdentity();
+        const coordinator = new SyncSagaCoordinator(mockKeystone);
+
+        await coordinator.sync({
+            source: sourceSpace,
+            dest: destSpace,
+            domainIbGibs: [root],
+            identity
+        });
+
+        // 3. Evolve DESTINATION (Simulate external update)
+        // We act "as if" we are on Dest side evolving it
+        console.log(`${lc} Evolving Destination (making Source behind)...`);
+        const childDest = await mut8Timeline({
+            timeline: root, // works because mut8Timeline just needs the ib/data/rel8ns/n, doesn't need to be "in" the space object-wise, but we persist to destSpace
+            mut8Opts: { dataToAddOrPatch: { n: 1, state: 'ahead' } },
+            metaspace,
+            space: destSpace,
+        });
+        const childDestAddr = getIbGibAddr({ ibGib: childDest });
+
+        // Verify Source DOES NOT have childDest
+        const getChildInSource = await getFromSpace({ space: sourceSpace, addr: childDestAddr });
+        iReckon(sir, getChildInSource.success).asTo('Source is behind').isGonnaBeFalse(); // Or success=true/addrsNotFound depending on impl
+
+        // 4. Run Sync from Source
+        // Checks:
+        // - Source should detect it is behind (or "conflict" in current generic terms).
+        // - Source should Pull 'childDest' from Dest.
+        // - Source should update itself.
+        console.log(`${lc} Running Sync (Pull)...`);
+        await coordinator.sync({
+            source: sourceSpace,
+            dest: destSpace,
+            domainIbGibs: [root], // We start with what Source knows (root)
+            identity
+        });
+
+        // 5. Verify Source Caught Up
+        const getChildInSourcePost = await getFromSpace({ space: sourceSpace, addr: childDestAddr });
+        iReckon(sir, getChildInSourcePost.success).asTo('Source pulled new frame').isGonnaBeTrue();
+        iReckon(sir, getChildInSourcePost.ibGibs?.[0]).asTo('Source has childDest').isGonnaBeTruthy();
+
+        console.log(`${lc} Verified Dest Ahead / Pull.`);
+    });
+});