@ibgib/core-gib 0.1.9 → 0.1.11

package/src/agent-helpers.mts

@@ -0,0 +1,159 @@
+/**
+ * @module agent-helpers
+ * 
+ * Helper functions designed to simplify common ibGib operations for agentic usage.
+ * These abstract away the low-level Factory_V1 details and provide clear, semantic
+ * 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 { 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 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>> {
+    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 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>> {
+    const lc = `[${createTimelineRootHelper.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 8f50a8cf0268742048f7c188feb5a825)`); }
+
+        // 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.`); }
+    }
+}
+
+/**
+ * Creates a valid, mock Keystone Service for testing purposes.
+ * This mocks the identity and signing logic needed for Sync operations.
+ */
+export async function getTestKeystoneServiceHelper(): Promise<KeystoneService_V1> {
+    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/keystone/keystone-config-builder.respec.mts

@@ -12,9 +12,9 @@ import { KEYSTONE_VERB_REVOKE, } from './keystone-constants.mjs';
 const logalot = GLOBAL_LOG_A_LOT;
 
 
-await respecfullyDear(sir, 'Config Builders', async () => {
+await respecfully(sir, 'Config Builders', async () => {
 
-    await ifWeMight(sir, 'createStandardPoolConfig defaults are correct', async () => {
+    await ifWe(sir, 'createStandardPoolConfig defaults are correct', async () => {
         const config = createStandardPoolConfig("test_salt") as KeystonePoolConfig_HashV1;
 
         iReckon(sir, config.salt).willEqual("test_salt");
@@ -32,7 +32,7 @@ await respecfullyDear(sir, 'Config Builders', async () => {
         iReckon(sir, config.allowedVerbs.length).willEqual(0);
     });
 
-    await ifWeMight(sir, 'createRevocationPoolConfig defaults are correct', async () => {
+    await ifWe(sir, 'createRevocationPoolConfig defaults are correct', async () => {
         const config = createRevocationPoolConfig("revoke_salt") as KeystonePoolConfig_HashV1;
 
         iReckon(sir, config.salt).willEqual("revoke_salt");

package/src/keystone/keystone-service-v1.respec.mts

@@ -200,7 +200,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Derivation Logic', async () => {
 
-        await ifWeMight(sir, 'derivePoolSecret with same inputs returns same output', async () => {
+        await ifWe(sir, 'derivePoolSecret with same inputs returns same output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -210,7 +210,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secret length').isGonnaBeTruthy();
         });
 
-        await ifWeMight(sir, 'derivePoolSecret with different master secret returns different output', async () => {
+        await ifWe(sir, 'derivePoolSecret with different master secret returns different output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -219,7 +219,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secrets differ').not.willEqual(secretB);
         });
 
-        await ifWeMight(sir, 'derivePoolSecret with different salt returns different output', async () => {
+        await ifWe(sir, 'derivePoolSecret with different salt returns different output', async () => {
             // Modify salt in a copy of config
             const configB = { ...config, salt: "OtherPool" };
             const strategyA = KeystoneStrategyFactory.create({ config });
@@ -234,7 +234,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Challenge/Solution Logic', async () => {
 
-        await ifWeMight(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
+        await ifWe(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "a3ff7843552870fc28bef2b"; // arbitrary random challengeId
@@ -253,7 +253,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('valid pair should pass').isGonnaBeTrue();
         });
 
-        await ifWeMight(sir, 'validateSolution fails for mismatched values', async () => {
+        await ifWe(sir, 'validateSolution fails for mismatched values', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "8c994f3ed598f150e25513"; // arbitrary random challengeId
@@ -269,7 +269,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('tampered solution should fail').isGonnaBeFalse();
         });
 
-        await ifWeMight(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
+        await ifWe(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
 
@@ -310,7 +310,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Genesis', async () => {
-        await ifWeMight(sir, 'creates a valid genesis frame and persists it', async () => {
+        await ifWe(sir, 'creates a valid genesis frame and persists it', async () => {
             const config = createStandardPoolConfig(POOL_ID_DEFAULT);
 
             genesisKeystone = await service.genesis({
@@ -338,7 +338,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Signing (Evolution)', async () => {
-        await ifWeMight(sir, 'evolves the keystone with a valid proof', async () => {
+        await ifWe(sir, 'evolves the keystone with a valid proof', async () => {
             const claim: Partial<KeystoneClaim> = {
                 target: "comment 123^gib",
                 verb: "post"
@@ -368,7 +368,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Validation', async () => {
-        await ifWeMight(sir, 'validates the genesis->signed transition', async () => {
+        await ifWe(sir, 'validates the genesis->signed transition', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: signedKeystone,
@@ -411,7 +411,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Wrong Secret (Forgery)', async () => {
-        await ifWeMight(sir, 'prevents creation of forged frames', async () => {
+        await ifWe(sir, 'prevents creation of forged frames', async () => {
             const claim: Partial<KeystoneClaim> = { target: "comment 123^gib", verb: "post" };
 
             let errorCaught = false;
@@ -440,7 +440,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Policy Violation (Restricted Verbs)', async () => {
-        await ifWeMight(sir, 'throws error if signing forbidden verb with restricted pool', async () => {
+        await ifWe(sir, 'throws error if signing forbidden verb with restricted pool', async () => {
             // Create a specific restricted pool config manually
             const restrictedPoolId = "read_only_pool";
             const restrictedConfig = createStandardPoolConfig(restrictedPoolId);
@@ -481,7 +481,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
 // SUITE D: REVOCATION
 // ===========================================================================
 
-await respecfullyDear(sir, 'Suite D: Revocation', async () => {
+await respecfully(sir, 'Suite D: Revocation', async () => {
 
     const service = new KeystoneService_V1();
     const masterSecret = "AliceSecret_RevokeTest";
@@ -509,7 +509,7 @@ await respecfullyDear(sir, 'Suite D: Revocation', async () => {
     await respecfully(sir, 'Revoke Lifecycle', async () => {
         let revokedKeystone: KeystoneIbGib_V1;
 
-        await ifWeMight(sir, 'successfully creates a revocation frame', async () => {
+        await ifWe(sir, 'successfully creates a revocation frame', async () => {
             revokedKeystone = await service.revoke({
                 latestKeystone: genesisKeystone,
                 masterSecret,
@@ -527,7 +527,7 @@ await respecfullyDear(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, data.revocationInfo!.proof.claim.verb).willEqual(KEYSTONE_VERB_REVOKE);
         });
 
-        await ifWeMight(sir, 'validates the revocation frame', async () => {
+        await ifWe(sir, 'validates the revocation frame', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: revokedKeystone!,
@@ -538,7 +538,7 @@ await respecfullyDear(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, errors.length).asTo('no validation errors').willEqual(0);
         });
 
-        await ifWeMight(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
+        await ifWe(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
             const data = revokedKeystone!.data!;
             const revokePool = data.challengePools.find(p => p.id === POOL_ID_REVOKE);
 
@@ -556,7 +556,7 @@ await respecfullyDear(sir, 'Suite D: Revocation', async () => {
 // SUITE E: STRUCTURAL EVOLUTION (addPools)
 // ===========================================================================
 
-await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async () => {
+await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
 
     const service = new KeystoneService_V1();
     const aliceSecret = "Alice_Master_Key";
@@ -615,7 +615,7 @@ await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async ()
     });
 
     await respecfully(sir, 'Happy Path', async () => {
-        await ifWeMight(sir, 'authorizes and adds a foreign pool', async () => {
+        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
             const bobPool = await createForeignPool("pool_bob", ["post"]);
 
             const updatedKeystone = await service.addPools({
@@ -654,7 +654,7 @@ await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async ()
     });
 
     await respecfully(sir, 'Permissions & Logic', async () => {
-        await ifWeMight(sir, 'fails if no pool allows "manage" verb', async () => {
+        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
             // 1. Create a restricted keystone
             const restrictedConfig = createStandardPoolConfig("read_only");
             restrictedConfig.allowedVerbs = ['read']; // No 'manage'
@@ -686,7 +686,7 @@ await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async ()
             iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
         });
 
-        await ifWeMight(sir, 'fails on ID collision', async () => {
+        await ifWe(sir, 'fails on ID collision', async () => {
             // Try to add "pool_bob" again (it was added in Happy Path)
             const duplicatePool = await createForeignPool("pool_bob");
 
@@ -713,7 +713,7 @@ await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async ()
 // SUITE E: STRUCTURAL EVOLUTION (addPools)
 // ===========================================================================
 
-await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async () => {
+await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
 
     const service = new KeystoneService_V1();
     const aliceSecret = "Alice_Master_Key";
@@ -772,7 +772,7 @@ await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async ()
     });
 
     await respecfully(sir, 'Happy Path', async () => {
-        await ifWeMight(sir, 'authorizes and adds a foreign pool', async () => {
+        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
             const bobPool = await createForeignPool("pool_bob", ["post"]);
 
             const updatedKeystone = await service.addPools({
@@ -811,7 +811,7 @@ await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async ()
     });
 
     await respecfully(sir, 'Permissions & Logic', async () => {
-        await ifWeMight(sir, 'fails if no pool allows "manage" verb', async () => {
+        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
             // 1. Create a restricted keystone (read-only)
             const restrictedConfig = createStandardPoolConfig("read_only");
             restrictedConfig.allowedVerbs = ['read']; // No 'manage'
@@ -843,7 +843,7 @@ await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async ()
             iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
         });
 
-        await ifWeMight(sir, 'fails on ID collision', async () => {
+        await ifWe(sir, 'fails on ID collision', async () => {
             // Try to add "pool_bob" again (it was added in Happy Path)
             const duplicatePool = await createForeignPool("pool_bob");
 
@@ -870,7 +870,7 @@ await respecfullyDear(sir, 'Suite E: Structural Evolution (addPools)', async ()
 // SUITE F: DEEP INSPECTION (Granularity & Serialization)
 // ===========================================================================
 
-await respecfullyDear(sir, 'Suite F: Deep Inspection', async () => {
+await respecfully(sir, 'Suite F: Deep Inspection', async () => {
 
     const service = new KeystoneService_V1();
     const aliceSecret = "Alice_Deep_Inspect";
@@ -880,6 +880,8 @@ await respecfullyDear(sir, 'Suite F: Deep Inspection', async () => {
     let mockMetaspace: any;
     let genesisKeystone: KeystoneIbGib_V1;
 
+    let signedKeystone: KeystoneIbGib_V1;
+
     // We use a specific hybrid config to test exact selection logic
     const hybridConfig = createStandardPoolConfig(salt) as KeystonePoolConfig_HashV1;
     // 2 FIFO + 2 Random = 4 Total per sign
@@ -900,9 +902,8 @@ await respecfullyDear(sir, 'Suite F: Deep Inspection', async () => {
     });
 
     await respecfully(sir, 'Proof Granularity & Math', async () => {
-        let signedKeystone: KeystoneIbGib_V1;
 
-        await ifWeMight(sir, 'generates exactly the expected number of solutions', async () => {
+        await ifWe(sir, 'generates exactly the expected number of solutions', async () => {
             signedKeystone = await service.sign({
                 latestKeystone: genesisKeystone,
                 masterSecret: aliceSecret,
@@ -919,7 +920,7 @@ await respecfullyDear(sir, 'Suite F: Deep Inspection', async () => {
             iReckon(sir, solutions.length).asTo('solution count').willEqual(4);
         });
 
-        await ifWeMight(sir, 'verifies the math manually (White-box Crypto Check)', async () => {
+        await ifWe(sir, 'verifies the math manually (White-box Crypto Check)', async () => {
             const proof = signedKeystone.data!.proofs[0];
             const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === salt)!;
 
@@ -948,7 +949,7 @@ await respecfullyDear(sir, 'Suite F: Deep Inspection', async () => {
             }
         });
 
-        await ifWeMight(sir, 'verifies FIFO logic (Deterministic Selection)', async () => {
+        await ifWe(sir, 'verifies FIFO logic (Deterministic Selection)', async () => {
             const proof = signedKeystone.data!.proofs[0];
             const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === salt)!;
 
@@ -968,45 +969,50 @@ await respecfullyDear(sir, 'Suite F: Deep Inspection', async () => {
         });
     });
 
-    // await respecfully(sir, 'DTO & Serialization', async () => {
+    await respecfully(sir, 'DTO & Serialization', async () => {
+
+        await ifWe(sir, 'survives a clone/JSON-cycle without corruption', async () => {
+            // 1. Create a DTO (simulate network transmission/storage)
+            // 'clone' does a JSON stringify/parse under the hood (usually) or structured clone.
+            const dto = clone(signedKeystone);
 
-    //     await ifWeMight(sir, 'survives a clone/JSON-cycle without corruption', async () => {
-    //         // 1. Create a DTO (simulate network transmission/storage)
-    //         // 'clone' does a JSON stringify/parse under the hood (usually) or structured clone.
-    //         const dto = clone(signedKeystone);
+            // 2. Structural checks
+            iReckon(sir, dto).asTo('dto exists').isGonnaBeTruthy();
+            iReckon(sir, dto.data).asTo('dto data').isGonnaBeTruthy();
+            iReckon(sir, dto.data!.proofs).asTo('dto proofs').isGonnaBeTruthy();
+
+            // 3. Functional check: Can the service validate this DTO?
+            // This ensures no prototypes or hidden properties were lost that the service depends on.
+            const errors = await service.validate({
+                prevIbGib: genesisKeystone,
+                currentIbGib: dto, // Passing the DTO, not the original object
+            });
 
-    //         // 2. Structural checks
-    //         iReckon(sir, dto).asTo('dto exists').isGonnaBeTruthy();
-    //         iReckon(sir, dto.data).asTo('dto data').isGonnaBeTruthy();
-    //         iReckon(sir, dto.data!.proofs).asTo('dto proofs').isGonnaBeTruthy();
+            iReckon(sir, errors.length).asTo('DTO validation errors').willEqual(0);
+        });
 
-    //         // 3. Functional check: Can the service validate this DTO?
-    //         // This ensures no prototypes or hidden properties were lost that the service depends on.
-    //         const errors = await service.validate({
-    //             prevIbGib: genesisKeystone,
-    //             currentIbGib: dto, // Passing the DTO, not the original object
-    //         });
+        await ifWe(sir, 'ensures data contains no functions or circular refs', async () => {
+            // A crude but effective test: ensure JSON.stringify doesn't throw
+            // and the result is equal to the object (if we parsed it back).
 
-    //         iReckon(sir, errors.length).asTo('DTO validation errors').willEqual(0);
-    //     });
+            const jsonStr = JSON.stringify(signedKeystone);
+            const parsed = JSON.parse(jsonStr);
 
-    //     await ifWeMight(sir, 'ensures data contains no functions or circular refs', async () => {
-    //         // A crude but effective test: ensure JSON.stringify doesn't throw
-    //         // and the result is equal to the object (if we parsed it back).
+            // Compare specific deep fields
+            const originalSolution = signedKeystone.data!.proofs[0].solutions[0].value;
+            const parsedSolution = parsed.data.proofs[0].solutions[0].value;
 
-    //         const jsonStr = JSON.stringify(signedKeystone);
-    //         const parsed = JSON.parse(jsonStr);
+            iReckon(sir, parsedSolution).asTo('deep property survives stringify').willEqual(originalSolution);
 
-    //         // Compare specific deep fields
-    //         const originalSolution = signedKeystone.data!.proofs[0].solutions[0].value;
-    //         const parsedSolution = parsed.data.proofs[0].solutions[0].value;
+            // Ensure no extra properties were lost
+            // FIX: JSON.stringify removes keys with 'undefined' values. 
+            // We must filter the original keys to match this behavior for a fair comparison.
+            const origKeys = Object.keys(signedKeystone.data!)
+                .filter(k => (signedKeystone.data as any)[k] !== undefined);
 
-    //         iReckon(sir, parsedSolution).asTo('deep property survives stringify').willEqual(originalSolution);
+            const parsedKeys = Object.keys(parsed.data);
+            iReckon(sir, parsedKeys.length).asTo('key count matches').willEqual(origKeys.length);
+        });
 
-    //         // Ensure no extra properties were lost (rudimentary check)
-    //         const origKeys = Object.keys(signedKeystone.data!);
-    //         const parsedKeys = Object.keys(parsed.data);
-    //         iReckon(sir, parsedKeys.length).asTo('key count matches').willEqual(origKeys.length);
-    //     });
-    // });
+    });
 });

package/src/sync/sync-constants.mts

@@ -0,0 +1,24 @@
+export const SYNC_ATOM = "sync";
+
+/**
+ * Protocol version string for V1.
+ */
+export const SYNC_PROTOCOL_V1 = "sync 1.0.0";
+
+export const SYNC_STAGE_INIT = "init";
+export const SYNC_STAGE_REQUEST = "request";
+export const SYNC_STAGE_DELTA = "delta";
+export const SYNC_STAGE_COMMIT = "commit";
+
+export type SyncStage =
+    | typeof SYNC_STAGE_INIT
+    | typeof SYNC_STAGE_REQUEST
+    | typeof SYNC_STAGE_DELTA
+    | typeof SYNC_STAGE_COMMIT;
+
+export const SyncStage = {
+    init: SYNC_STAGE_INIT,
+    request: SYNC_STAGE_REQUEST,
+    delta: SYNC_STAGE_DELTA,
+    commit: SYNC_STAGE_COMMIT,
+} as const;

package/src/sync/sync-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_ATOM } from "./sync-constants.mjs";
+import { SyncData_V1, SyncIbInfo_V1 } from "./sync-types.mjs";
+
+const GLOBAL_LOG_A_LOT = false; // Todo: import from core constants if needed
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * Constructs the standard 'ib' string for a Sync frame.
+ */
+export async function getSyncIb({
+    data,
+}: {
+    data: SyncData_V1,
+}): Promise<Ib> {
+    const lc = `[${getSyncIb.name}]`;
+    try {
+        // sync uuid stage
+        // e.g. "sync 1234-5678 init"
+        const ib = [
+            SYNC_ATOM,
+            data.uuid,
+            data.stage
+        ].join(' ');
+
+        return ib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Parses a standard Sync 'ib' string.
+ */
+export async function parseSyncIb({
+    ib,
+}: {
+    ib: Ib,
+}): Promise<SyncIbInfo_V1> {
+    const lc = `[${parseSyncIb.name}]`;
+    try {
+        const parts = ib.split(' ');
+        if (parts.length !== 3) {
+            throw new Error(`Invalid sync ib. Expected 3 parts [atom uuid stage]. Got ${parts.length}. (E: 7c8d9...)`);
+        }
+        const [atom, uuid, stage] = parts;
+
+        if (atom !== SYNC_ATOM) {
+            throw new Error(`Invalid sync ib. Expected atom '${SYNC_ATOM}', got '${atom}'. (E: 8f9e1...)`);
+        }
+
+        return { atom, uuid, stage: stage as any };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}