@ibgib/core-gib 0.1.9 → 0.1.11

package/dist/sync/sync-types.d.mts

@@ -0,0 +1,103 @@
+import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { KeystoneIbGib_V1 } from "../keystone/keystone-types.mjs";
+import { SYNC_ATOM, SyncStage } from "./sync-constants.mjs";
+/**
+ * The "Hello" of the sync protocol.
+ * Exchanges knowledge vectors (what I have) and identity (who I am).
+ */
+export interface SyncInitData {
+    /**
+     * Map of TJP (Traffic Joint Point) to latest known Gib/Hash.
+     * Use this to calculate what is missing (Delta).
+     */
+    knowledgeVector: {
+        [tjp: string]: string;
+    };
+    /**
+     * The Keystone Identity of the sender.
+     * Required for the first handshake or if the receiver doesn't know the sender.
+     */
+    identity?: KeystoneIbGib_V1;
+    /**
+     * What the sender wants to do.
+     * e.g. "push" (I have data for you) or "pull" (Give me data).
+     * @default 'push'
+     */
+    mode?: 'push' | 'pull';
+}
+/**
+ * A specific request for data.
+ * Used for "pull" based deltas or fixing gaps (packet loss).
+ */
+export interface SyncRequestData {
+    /**
+     * The ibGib addresses requested.
+     */
+    addrs: string[];
+}
+/**
+ * The "Body" of the sync protocol.
+ * Carries the manifests of data to be transferred.
+ */
+export interface SyncDeltaData {
+    /**
+     * The list of ibGib addresses being transferred.
+     * The actual data is streamed/batched separately.
+     */
+    payloadAddrs: string[];
+}
+/**
+ * The "Seal" of the sync protocol.
+ * The authority is derived from the `identity` relation on the Keystone Frame.
+ */
+export interface SyncCommitData {
+    /**
+     * True if the session completed successfully from the sender's perspective.
+     */
+    success: boolean;
+    /**
+     * Optional verification metadata (e.g. success count).
+     */
+    successCount?: number;
+    /**
+     * If failed, the reasons why.
+     */
+    errors?: string[];
+}
+export interface SyncIbInfo_V1 {
+    atom: typeof SYNC_ATOM;
+    uuid: string;
+    stage: SyncStage;
+}
+export interface SyncData_V1 extends IbGibData_V1 {
+    /**
+     * Unique ID for this synchronization session.
+     * Corresponds to `uuid` in standard IbGibData.
+     */
+    uuid: string;
+    /**
+     * Current stage of the protocol.
+     */
+    stage: SyncStage;
+    /**
+     * Optional absolute timestamp (Unix ms) after which this frame should be considered void.
+     * Useful for:
+     * 1. Auth Challenges (Login offers expiring).
+     * 2. Rate limiting / Backpressure (Don't process this old request).
+     */
+    expirationTimestamp?: string;
+    /**
+     * Polymorphic payload based on stage.
+     */
+    payload: SyncInitData | SyncRequestData | SyncDeltaData | SyncCommitData;
+}
+export interface SyncRel8ns_V1 extends IbGibRel8ns_V1 {
+    /**
+     * Link to the Keystone Identity performing this step.
+     * This MUST point to the specific Keystone Frame that authorizes this sync frame.
+     */
+    identity?: string[];
+}
+export interface SyncIbGib_V1 extends IbGib_V1<SyncData_V1, SyncRel8ns_V1> {
+}
+//# sourceMappingURL=sync-types.d.mts.map

package/dist/sync/sync-types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-types.d.mts","sourceRoot":"","sources":["../../src/sync/sync-types.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAiB,MAAM,gCAAgC,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAM5D;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,eAAe,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAE5B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B;;OAEG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B;;;OAGG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC3B;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAMD,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,OAAO,SAAS,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CACpB;AAED,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC7C;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,OAAO,EAAE,YAAY,GAAG,eAAe,GAAG,aAAa,GAAG,cAAc,CAAC;CAC5E;AAED,MAAM,WAAW,aAAc,SAAQ,cAAc;IACjD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,YAAa,SAAQ,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;CAAI"}

package/dist/sync/sync-types.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sync-types.mjs.map

package/dist/sync/sync-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-types.mjs","sourceRoot":"","sources":["../../src/sync/sync-types.mts"],"names":[],"mappings":""}

package/dist/test/mock-space.d.mts

@@ -0,0 +1,39 @@
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+/**
+ * A simple in-memory map acting as a Space.
+ * Pure Storage. No Indexing logic.
+ *
+ * Copied/Adapted from Keystone Respecs.
+ */
+export declare class MockIbGibSpace {
+    name: string;
+    store: Map<string, IbGib_V1<import("@ibgib/ts-gib/dist/V1/types.mjs").IbGibData_V1, import("@ibgib/ts-gib/dist/V1/types.mjs").IbGibRel8ns_V1>>;
+    constructor(name?: string);
+    put({ ibGib }: {
+        ibGib: IbGib_V1;
+    }): Promise<void>;
+    get({ addr }: {
+        addr: string;
+    }): Promise<IbGib_V1 | null>;
+    witness(arg: any): Promise<any>;
+}
+/**
+ * A partial mock of Metaspace.
+ */
+export declare class MockMetaspaceService {
+    space: MockIbGibSpace;
+    /**
+     * Map of TJP Gib (Timeline ID) -> Latest IbGib Addr (Head)
+     */
+    timelineHeads: Map<string, string>;
+    constructor(space: MockIbGibSpace);
+    getLocalUserSpace({ lock }: {
+        lock: boolean;
+    }): Promise<MockIbGibSpace>;
+    put(args: any): Promise<void>;
+    registerNewIbGib(args: {
+        ibGib: IbGib_V1;
+        space?: any;
+    }): Promise<void>;
+}
+//# sourceMappingURL=mock-space.d.mts.map

package/dist/test/mock-space.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-space.d.mts","sourceRoot":"","sources":["../../src/test/mock-space.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAG3D;;;;;GAKG;AACH,qBAAa,cAAc;IAGJ,IAAI,EAAE,MAAM;IAF/B,KAAK,0IAA+B;gBAEjB,IAAI,GAAE,MAAqB;IAExC,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE;QAAE,KAAK,EAAE,QAAQ,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAKzD,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;CAoBxC;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAOV,KAAK,EAAE,cAAc;IALxC;;OAEG;IACH,aAAa,sBAA6B;gBAEvB,KAAK,EAAE,cAAc;IAElC,iBAAiB,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAIvE,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7B,gBAAgB,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,QAAQ,CAAC;QAAC,KAAK,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBhF"}

package/dist/test/mock-space.mjs

@@ -0,0 +1,79 @@
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+/**
+ * A simple in-memory map acting as a Space.
+ * Pure Storage. No Indexing logic.
+ *
+ * Copied/Adapted from Keystone Respecs.
+ */
+export class MockIbGibSpace {
+    name;
+    store = new Map();
+    constructor(name = "mock_space") {
+        this.name = name;
+    }
+    async put({ ibGib }) {
+        const addr = getIbGibAddr({ ibGib });
+        this.store.set(addr, JSON.parse(JSON.stringify(ibGib))); // Deep copy
+    }
+    async get({ addr }) {
+        const data = this.store.get(addr);
+        return data ? JSON.parse(JSON.stringify(data)) : null;
+    }
+    async witness(arg) {
+        const cmd = arg.data?.cmd;
+        if (cmd === 'get') {
+            const addrs = arg.data.ibGibAddrs || [];
+            const ibGibs = [];
+            for (const addr of addrs) {
+                const ig = await this.get({ addr });
+                if (ig)
+                    ibGibs.push(ig);
+            }
+            return { ibGibs };
+        }
+        if (cmd === 'put') {
+            const ibGibs = arg.ibGibs || [];
+            for (const ibGib of ibGibs) {
+                await this.put({ ibGib });
+            }
+            return { ibGibs: [] }; // Return empty result or whatever witness expects
+        }
+        return undefined;
+    }
+}
+/**
+ * A partial mock of Metaspace.
+ */
+export class MockMetaspaceService {
+    space;
+    /**
+     * Map of TJP Gib (Timeline ID) -> Latest IbGib Addr (Head)
+     */
+    timelineHeads = new Map();
+    constructor(space) {
+        this.space = space;
+    }
+    async getLocalUserSpace({ lock }) {
+        return this.space;
+    }
+    async put(args) {
+        const target = args.space || this.space;
+        return target.put(args);
+    }
+    async registerNewIbGib(args) {
+        const { ibGib } = args;
+        const targetSpace = args.space || this.space;
+        // 1. Ensure it is stored
+        await targetSpace.put({ ibGib });
+        // 2. Extract TJP
+        const gib = ibGib.gib || '';
+        let tjpGib = gib;
+        if (gib.includes('.')) {
+            const parts = gib.split('.');
+            tjpGib = parts.slice(1).join('.');
+        }
+        const addr = getIbGibAddr({ ibGib });
+        this.timelineHeads.set(tjpGib, addr);
+    }
+}
+//# sourceMappingURL=mock-space.mjs.map

package/dist/test/mock-space.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-space.mjs","sourceRoot":"","sources":["../../src/test/mock-space.mts"],"names":[],"mappings":"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"}

package/dist/timeline/timeline-api.respec.d.mts

@@ -0,0 +1,7 @@
+/**
+ * @module timeline-api.respec
+ *
+ * specs for the high-level timeline api.
+ */
+export {};
+//# sourceMappingURL=timeline-api.respec.d.mts.map

package/dist/timeline/timeline-api.respec.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-api.respec.d.mts","sourceRoot":"","sources":["../../src/timeline/timeline-api.respec.mts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/timeline/timeline-api.respec.mjs

@@ -0,0 +1,183 @@
+/**
+ * @module timeline-api.respec
+ *
+ * specs for the high-level timeline api.
+ */
+import { firstOfEach, ifWe, iReckon, respecfully } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { getLatestAddrs, getFromSpace } from '../witness/space/space-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { createTimeline, mut8Timeline, appendToTimeline, getHistory } from './timeline-api.mjs';
+import { Metaspace_Innerspace } from '../witness/space/metaspace/metaspace-innerspace/metaspace-innerspace.mjs';
+const maam = `[${import.meta.url}]`, sir = maam;
+respecfully(sir, `[timeline-api]`, async () => {
+    let space;
+    let metaspace;
+    firstOfEach(sir, async () => {
+        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; },
+        });
+        space = metaspace.zeroSpace;
+    });
+    await ifWe(sir, `createTimeline`, async () => {
+        const res = await createTimeline({
+            space,
+            metaspace,
+            data: { note: 'first timeline' },
+            ib: 'timeline',
+        });
+        const newTimeline = res.newIbGib;
+        iReckon(sir, newTimeline).asTo('newTimeline').isGonnaBeTruthy();
+        const addr = getIbGibAddr({ ibGib: newTimeline });
+        // verify persistence
+        const resGet = await getFromSpace({ addr, space });
+        iReckon(sir, resGet.success).asTo('persisted success').isGonnaBeTrue();
+        iReckon(sir, resGet.ibGibs[0]).asTo('persisted ibGib').isGonnaBe(newTimeline);
+    });
+    await ifWe(sir, `mut8Timeline`, async () => {
+        // Arrange
+        const resCreate = await createTimeline({
+            space,
+            metaspace,
+            data: { note: 'orig' },
+            ib: 'timeline',
+        });
+        const timeline = resCreate.newIbGib;
+        console.log(`[mut8Timeline] created timeline n=${timeline.data.n}`);
+        const initialPastLength = timeline.rel8ns?.past?.length || 0;
+        console.log(`[mut8Timeline] created timeline past length=${initialPastLength}`);
+        // Act
+        const mutatedTimeline = await mut8Timeline({
+            timeline,
+            metaspace,
+            space,
+            mut8Opts: {
+                dataToAddOrPatch: { note: 'mutated' },
+            }
+        });
+        console.log(`[mut8Timeline] mutated timeline n=${mutatedTimeline.data.n}`);
+        // Assert
+        iReckon(sir, mutatedTimeline).asTo('mutatedTimeline').isGonnaBeTruthy();
+        iReckon(sir, mutatedTimeline.data.note).asTo('data.note').isGonnaBe('mutated');
+        // n should increment by 1
+        const expectedN = (timeline.data.n || 0) + 1;
+        iReckon(sir, mutatedTimeline.data.n).asTo('data.n').isGonnaBe(expectedN);
+        iReckon(sir, mutatedTimeline.rel8ns.past).asTo('past').isGonnaBeTruthy();
+        // past length should include the previous frame + whatever it had
+        iReckon(sir, mutatedTimeline.rel8ns.past.length).asTo('past length').isGonnaBe(initialPastLength + 1);
+        iReckon(sir, mutatedTimeline.rel8ns.past.at(-1)).asTo('past addr').isGonnaBe(getIbGibAddr({ ibGib: timeline }));
+    });
+    await ifWe(sir, `appendToTimeline`, async () => {
+        // Arrange
+        const resCreate = await createTimeline({
+            space,
+            metaspace,
+            data: { n: 0 },
+            ib: 'timeline',
+        });
+        let timeline = resCreate.newIbGib;
+        const rel8nInfos = [{
+                rel8nName: 'attachment',
+                ibGibs: [timeline] // just attaching itself as a test, weird but valid structure
+            }];
+        const timelinePastLength = timeline.rel8ns?.past?.length || 0;
+        // Act
+        const appendedTimeline = await appendToTimeline({
+            timeline,
+            rel8nInfos,
+            metaspace,
+            space,
+        });
+        // Assert
+        iReckon(sir, appendedTimeline).asTo('appendedTimeline').isGonnaBeTruthy();
+        iReckon(sir, appendedTimeline.rel8ns.attachment).asTo('attachment').isGonnaBeTruthy();
+        iReckon(sir, appendedTimeline.rel8ns.past?.length).asTo('past').isGonnaBe(timelinePastLength + 1);
+    });
+    await ifWe(sir, `getHistory`, async () => {
+        // Arrange
+        let t0 = (await createTimeline({ space, metaspace, data: { n: 0 }, ib: 'timeline' })).newIbGib;
+        let t1 = await mut8Timeline({ timeline: t0, metaspace, space, mut8Opts: { dataToAddOrPatch: { n: 1 } } });
+        let t2 = await mut8Timeline({ timeline: t1, metaspace, space, mut8Opts: { dataToAddOrPatch: { n: 2 } } });
+        // Act
+        const history = await getHistory({
+            timeline: t2,
+            metaspace,
+            space,
+        });
+        // Assert
+        // t0 is actually 2nd frame (fork -> mut8).
+        // so history is [genesis, t0, t1]. length 3.
+        iReckon(sir, history.orderedPastIbGibs.length).asTo('history length').isGonnaBe(3);
+        // index 0 is genesis (the fork)
+        // index 1 is t0
+        // index 2 is t1
+        iReckon(sir, getIbGibAddr({ ibGib: history.orderedPastIbGibs[1] })).asTo('t0').isGonnaBe(getIbGibAddr({ ibGib: t0 }));
+        iReckon(sir, getIbGibAddr({ ibGib: history.orderedPastIbGibs[2] })).asTo('t1').isGonnaBe(getIbGibAddr({ ibGib: t1 }));
+        iReckon(sir, getIbGibAddr({ ibGib: history.headIbGib })).asTo('head').isGonnaBe(getIbGibAddr({ ibGib: t2 }));
+    });
+    await ifWe(sir, `Concurrency & Locking (Stress Test)`, async () => {
+        // const concurrencyLevels = [1, 2, 5, 50, 1000]; // too slow, because the locking mechanism doesn't scale well.
+        const concurrencyLevels = [1, 2, 5, 50];
+        for (const N of concurrencyLevels) {
+            console.log(`[Stress Test] Testing concurrency level: ${N}`);
+            // Arrange: Baseline
+            let tInitial = (await createTimeline({
+                space,
+                metaspace,
+                data: { n: 0, testId: `concurrent-${N}` },
+                ib: 'timeline',
+            })).newIbGib;
+            // Initial state check
+            const initialN = (tInitial.data.n || 0); // should be 1
+            const historyInitial = await getHistory({ timeline: tInitial, metaspace, space });
+            const initialHistoryLength = historyInitial.orderedPastIbGibs.length; // should be 1 (genesis)
+            // Act: Launch N mutations simultaneously
+            const promises = [];
+            for (let i = 0; i < N; i++) {
+                promises.push(mut8Timeline({
+                    timeline: tInitial, // All start referencing the same initial frame (or logically the timeline itself)
+                    // Note: In reality, if we pass the *same* object tInitial, mut8Timeline should
+                    // resolve the *latest* inside the function.
+                    metaspace,
+                    space,
+                    mut8Opts: {
+                        dataToAddOrPatch: {
+                            uniq: i, // distinct data to ensure unique hashes if needed
+                        }
+                    }
+                    // No skipLock! We want them to contend.
+                }));
+            }
+            try {
+                // Wait for all to complete
+                await Promise.all(promises);
+                // Verification
+                // 1. Get Latest Address
+                const resLatest = await getLatestAddrs({ ibGibs: [tInitial], space });
+                const latestAddr = resLatest.data.latestAddrsMap[getIbGibAddr({ ibGib: tInitial })];
+                iReckon(sir, latestAddr).asTo(`[N=${N}] latestAddr exists`).isGonnaBeTruthy();
+                // 2. Load the latest frame
+                const resGet = await getFromSpace({ addr: latestAddr, space });
+                const latestIbGib = resGet.ibGibs[0];
+                // 3. Verify data.n
+                // Initial n=1. We did N mutations.
+                // Each mutation increments nCounter.
+                const expectedN = initialN + N;
+                iReckon(sir, latestIbGib.data.n).asTo(`[N=${N}] data.n should be ${expectedN}`).isGonnaBe(expectedN);
+                // 4. Verify Lineage (no divergence)
+                // History length should be initialHistoryLength + N
+                const history = await getHistory({ timeline: latestIbGib, metaspace, space });
+                const expectedHistoryLength = initialHistoryLength + N;
+                iReckon(sir, history.orderedPastIbGibs.length).asTo(`[N=${N}] history length`).isGonnaBe(expectedHistoryLength);
+                console.log(`[Stress Test] [N=${N}] SUCCESS. Final n=${latestIbGib.data.n}`);
+            }
+            catch (err) {
+                console.error(`[Stress Test] [N=${N}] FAILED:`, err);
+                throw err;
+            }
+        }
+    });
+});
+//# sourceMappingURL=timeline-api.respec.mjs.map

package/dist/timeline/timeline-api.respec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-api.respec.mjs","sourceRoot":"","sources":["../../src/timeline/timeline-api.respec.mts"],"names":[],"mappings":"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"}