@ibgib/core-gib 0.1.60 → 0.1.62

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

@@ -10,9 +10,11 @@ import { GLOBAL_LOG_A_LOT } from '../core-constants.mjs';
 import { KeystoneStrategyFactory } from './strategy/keystone-strategy-factory.mjs';
 import { KeystoneChallengePool, KeystoneClaim, KeystoneIbGib_V1, KeystonePoolConfig_HashV1 } from './keystone-types.mjs';
 import { createRevocationPoolConfig, createStandardPoolConfig } from './keystone-config-builder.mjs';
-import { POOL_ID_DEFAULT, POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE, KEYSTONE_VERB_MANAGE } from './keystone-constants.mjs';
-import { KeystoneService_V1 } from './keystone-service-v1.mjs';
-import { addToBindingMap } from './keystone-helpers.mjs';
+import { POOL_ID_DEFAULT, POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE, KEYSTONE_VERB_MANAGE, POOL_ID_MANAGE } from './keystone-constants.mjs';
+import { KeystoneService_V1, } from './keystone-service-v1.mjs';
+import { selectChallengeIds, validateChallengePool, validateKeystoneIb, validateKeystoneTransition, validateGenesisKeystone } from './keystone-helpers.mjs';
+import { KeystoneProfileBuilder } from './policy/keystone-profile-builder.mjs';
+import { getTjpAddr } from '../common/other/ibgib-helper.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -36,16 +38,55 @@ class MockIbGibSpace {
         return data ? JSON.parse(JSON.stringify(data)) : null;
     }
 
+    async argy({ argData, ibGibs }: { argData: any; ibGibs?: IbGib_V1[] }): Promise<any> {
+        return {
+            ib: 'arg^gib',
+            gib: 'arg_gib',
+            data: argData,
+            ibGibs,
+        };
+    }
+
     async witness(arg: any): Promise<any> {
         const cmd = arg.data?.cmd;
+        const cmdModifiers = arg.data?.cmdModifiers || [];
         if (cmd === 'get') {
             const addrs = arg.data.ibGibAddrs || [];
-            const ibGibs: IbGib_V1[] = [];
-            for (const addr of addrs) {
-                const x = await this.get({ addr });
-                if (x) { ibGibs.push(x); }
+            if (cmdModifiers.includes('latest') && cmdModifiers.includes('addrs')) {
+                const latestAddrsMap: { [addr: string]: string } = {};
+                for (const queryAddr of addrs) {
+                    const queryTjpGib = queryAddr.includes('.') ? queryAddr.split('.')[1] : queryAddr.split('^')[1];
+                    let latestAddr = queryAddr;
+                    let maxN = -1;
+                    for (const [addr, ibGib] of this.store.entries()) {
+                        const tjpGib = addr.includes('.') ? addr.split('.')[1] : addr.split('^')[1];
+                        if (tjpGib === queryTjpGib) {
+                            const n = ibGib.data?.n ?? 0;
+                            if (n > maxN) {
+                                maxN = n;
+                                latestAddr = addr;
+                            }
+                        }
+                    }
+                    latestAddrsMap[queryAddr] = latestAddr;
+                }
+                return {
+                    data: {
+                        success: true,
+                        latestAddrsMap,
+                    }
+                };
+            } else {
+                const ibGibs: IbGib_V1[] = [];
+                for (const addr of addrs) {
+                    const x = await this.get({ addr });
+                    if (x) { ibGibs.push(x); }
+                }
+                return {
+                    data: { success: true },
+                    ibGibs,
+                };
             }
-            return { ibGibs };
         }
         return undefined;
     }
@@ -80,6 +121,15 @@ class MockMetaspaceService {
         return target.put(args);
     }
 
+    async get(args: { addr: string, space?: any }): Promise<{ success: boolean, ibGibs?: IbGib_V1[] }> {
+        const target = args.space || this.space;
+        const x = await target.get({ addr: args.addr });
+        return {
+            success: !!x,
+            ibGibs: x ? [x] : [],
+        };
+    }
+
     /**
      * Tracks the latest version of an ibGib timeline.
      */
@@ -131,7 +181,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Derivation Logic', async () => {
 
-        await ifWe(sir, 'derivePoolSecret with same inputs returns same output', async () => {
+        await ifWeMight(sir, 'derivePoolSecret with same inputs returns same output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -141,7 +191,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secret length').isGonnaBeTruthy();
         });
 
-        await ifWe(sir, 'derivePoolSecret with different master secret returns different output', async () => {
+        await ifWeMight(sir, 'derivePoolSecret with different master secret returns different output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -150,7 +200,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secrets differ').not.willEqual(secretB);
         });
 
-        await ifWe(sir, 'derivePoolSecret with different salt returns different output', async () => {
+        await ifWeMight(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 });
@@ -165,7 +215,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Challenge/Solution Logic', async () => {
 
-        await ifWe(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
+        await ifWeMight(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "a3ff7843552870fc28bef2b"; // arbitrary random challengeId
@@ -184,7 +234,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('valid pair should pass').isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'validateSolution fails for mismatched values', async () => {
+        await ifWeMight(sir, 'validateSolution fails for mismatched values', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "8c994f3ed598f150e25513"; // arbitrary random challengeId
@@ -200,7 +250,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('tampered solution should fail').isGonnaBeFalse();
         });
 
-        await ifWe(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
+        await ifWeMight(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
 
@@ -241,7 +291,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Genesis', async () => {
-        await ifWe(sir, 'creates a valid genesis frame and persists it', async () => {
+        await ifWeMight(sir, 'creates a valid genesis frame and persists it', async () => {
             const salt = (await getUUID()).substring(0, 16);
             const config = createStandardPoolConfig({
                 id: POOL_ID_DEFAULT,
@@ -273,7 +323,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Signing (Evolution)', async () => {
-        await ifWe(sir, 'evolves the keystone with a valid proof', async () => {
+        await ifWeMight(sir, 'evolves the keystone with a valid proof', async () => {
             const claim: Partial<KeystoneClaim> = {
                 target: "comment 123^gib",
                 verb: "post"
@@ -303,7 +353,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Validation', async () => {
-        await ifWe(sir, 'validates the genesis->signed transition', async () => {
+        await ifWeMight(sir, 'validates the genesis->signed transition', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: signedKeystone,
@@ -352,7 +402,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Wrong Secret (Forgery)', async () => {
-        await ifWe(sir, 'prevents creation of forged frames', async () => {
+        await ifWeMight(sir, 'prevents creation of forged frames', async () => {
             const claim: Partial<KeystoneClaim> = { target: "comment 123^gib", verb: "post" };
 
             let errorCaught = false;
@@ -381,7 +431,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Policy Violation (Restricted Verbs)', async () => {
-        await ifWe(sir, 'throws error if signing forbidden verb with restricted pool', async () => {
+        await ifWeMight(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({
@@ -461,7 +511,7 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
     await respecfully(sir, 'Revoke Lifecycle', async () => {
         let revokedKeystone: KeystoneIbGib_V1;
 
-        await ifWe(sir, 'successfully creates a revocation frame', async () => {
+        await ifWeMight(sir, 'successfully creates a revocation frame', async () => {
             revokedKeystone = await service.revoke({
                 latestKeystone: genesisKeystone,
                 masterSecret,
@@ -479,7 +529,7 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, data.revocationInfo!.proof.claim.verb).willEqual(KEYSTONE_VERB_REVOKE);
         });
 
-        await ifWe(sir, 'validates the revocation frame', async () => {
+        await ifWeMight(sir, 'validates the revocation frame', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: revokedKeystone!,
@@ -490,7 +540,7 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, errors.length).asTo('no validation errors').willEqual(0);
         });
 
-        await ifWe(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
+        await ifWeMight(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
             const data = revokedKeystone!.data!;
             const revokePool = data.challengePools.find(p => p.id === POOL_ID_REVOKE);
 
@@ -528,7 +578,6 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
         const strategy = KeystoneStrategyFactory.create({ config });
         const poolSecret = await strategy.derivePoolSecret({ masterSecret: bobSecret });
         const challenges: { [id: string]: any } = {};
-        const bindingMap: { [char: string]: string[] } = {};
 
         for (let i = 0; i < 10; i++) {
             // Manually replicate ID gen for test
@@ -540,14 +589,12 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             });
             const challenge = await strategy.generateChallenge({ solution });
             challenges[challengeId] = challenge;
-            addToBindingMap(bindingMap, challengeId);
         }
 
         return {
             id,
             config,
             challenges,
-            bindingMap,
             isForeign: true,
             metadata: { owner: 'Bob' }
         };
@@ -569,7 +616,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Happy Path', async () => {
-        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
+        await ifWeMight(sir, 'authorizes and adds a foreign pool', async () => {
             const bobPool = await createForeignPool("pool_bob", ["post"]);
 
             const updatedKeystone = await service.addPools({
@@ -608,7 +655,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Permissions & Logic', async () => {
-        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
+        await ifWeMight(sir, 'fails if no pool allows "manage" verb', async () => {
             // 1. Create a restricted keystone
             let id = "read_only";
             const restrictedConfig = createStandardPoolConfig({ id, salt: id });
@@ -641,7 +688,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'fails on ID collision', async () => {
+        await ifWeMight(sir, 'fails on ID collision', async () => {
             // Try to add "pool_bob" again (it was added in Happy Path)
             const duplicatePool = await createForeignPool("pool_bob");
 
@@ -688,7 +735,6 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
         const strategy = KeystoneStrategyFactory.create({ config });
         const poolSecret = await strategy.derivePoolSecret({ masterSecret: bobSecret });
         const challenges: { [id: string]: any } = {};
-        const bindingMap: { [char: string]: string[] } = {};
 
         // Generate a small set of challenges
         for (let i = 0; i < 10; i++) {
@@ -700,14 +746,12 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             });
             const challenge = await strategy.generateChallenge({ solution });
             challenges[challengeId] = challenge;
-            addToBindingMap(bindingMap, challengeId);
         }
 
         return {
             id,
             config,
             challenges,
-            bindingMap,
             isForeign: true,
             metadata: { owner: 'Bob', role: 'Delegate' }
         };
@@ -732,7 +776,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Happy Path', async () => {
-        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
+        await ifWeMight(sir, 'authorizes and adds a foreign pool', async () => {
             const bobPool = await createForeignPool("pool_bob", ["post"]);
 
             const updatedKeystone = await service.addPools({
@@ -771,7 +815,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Permissions & Logic', async () => {
-        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
+        await ifWeMight(sir, 'fails if no pool allows "manage" verb', async () => {
             // 1. Create a restricted keystone (read-only)
             let id = "read_only";
             const restrictedConfig = createStandardPoolConfig({ id, salt: id });
@@ -804,7 +848,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'fails on ID collision', async () => {
+        await ifWeMight(sir, 'fails on ID collision', async () => {
             // Try to add "pool_bob" again (it was added in Happy Path)
             const duplicatePool = await createForeignPool("pool_bob");
 
@@ -866,7 +910,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
 
     await respecfully(sir, 'Proof Granularity & Math', async () => {
 
-        await ifWe(sir, 'generates exactly the expected number of solutions', async () => {
+        await ifWeMight(sir, 'generates exactly the expected number of solutions', async () => {
             signedKeystone = await service.sign({
                 latestKeystone: genesisKeystone,
                 masterSecret: aliceSecret,
@@ -883,7 +927,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             iReckon(sir, solutions.length).asTo('solution count').willEqual(4);
         });
 
-        await ifWe(sir, 'verifies the math manually (White-box Crypto Check)', async () => {
+        await ifWeMight(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 === poolId)!;
 
@@ -912,7 +956,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             }
         });
 
-        await ifWe(sir, 'verifies FIFO logic (Deterministic Selection)', async () => {
+        await ifWeMight(sir, 'verifies FIFO logic (Deterministic Selection)', async () => {
             const proof = signedKeystone.data!.proofs[0];
             const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === poolId)!;
 
@@ -930,11 +974,75 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             iReckon(sir, hasFirst).asTo(`Solution includes 1st FIFO ID (${expectedFifoIds[0]})`).isGonnaBeTrue();
             iReckon(sir, hasSecond).asTo(`Solution includes 2nd FIFO ID (${expectedFifoIds[1]})`).isGonnaBeTrue();
         });
+
+        await ifWeMight(sir, 'verifies Next-Gen Hash-Based Target Binding Selection', async () => {
+            const bindingConfig = createStandardPoolConfig({
+                id: "binding_pool",
+                salt: "binding_salt",
+                sequential: 0,
+                random: 0,
+                targetBinding: 3,
+                size: 20
+            }) as KeystonePoolConfig_HashV1;
+
+            const tempGenesis = await service.genesis({
+                masterSecret: aliceSecret,
+                configs: [bindingConfig],
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+
+            // Evolve using the binding pool
+            const evolved = await service.sign({
+                latestKeystone: tempGenesis,
+                masterSecret: aliceSecret,
+                poolId: "binding_pool",
+                claim: {
+                    verb: "sign",
+                    target: "some_target_address^gib"
+                },
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+
+            const proof = evolved.data!.proofs[0];
+            iReckon(sir, proof.solutions.length).asTo('proof solutions count').willEqual(3);
+
+            // Now, let's verify that the selection is perfectly deterministic.
+            // If we run selectChallengeIds manually with the same pool and target, it must return the same IDs.
+            const poolSnapshot = tempGenesis.data!.challengePools.find(p => p.id === "binding_pool")!;
+            const selectedIds = await selectChallengeIds({
+                pool: poolSnapshot,
+                targetAddr: "some_target_address^gib"
+            });
+
+            const proofIds = proof.solutions.map(s => s.challengeId);
+            iReckon(sir, selectedIds.length).asTo('selected IDs count').willEqual(3);
+            for (const id of selectedIds) {
+                iReckon(sir, proofIds.includes(id)).asTo(`proof includes selected ID ${id}`).isGonnaBeTrue();
+            }
+        });
+
+        await ifWeMight(sir, 'fails validation if total requested challenges >= size', async () => {
+            const invalidConfig = createStandardPoolConfig({
+                id: "invalid_pool",
+                salt: "invalid_salt",
+                sequential: 5,
+                random: 5,
+                targetBinding: 6,
+                size: 15 // total requested is 5+5+6 = 16 >= 15
+            });
+
+            const errors = await validateChallengePool({ pool: { id: "invalid_pool", config: invalidConfig, challenges: {} } });
+            iReckon(sir, errors.length > 0).asTo('errors length is positive').isGonnaBeTrue();
+            const hasCorrectError = errors.some(e => e.includes("Total requested challenges"));
+            iReckon(sir, hasCorrectError).asTo('validation error content').isGonnaBeTrue();
+        });
     });
 
     await respecfully(sir, 'DTO & Serialization', async () => {
 
-        await ifWe(sir, 'survives a clone/JSON-cycle without corruption', async () => {
+        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);
@@ -954,7 +1062,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             iReckon(sir, errors.length).asTo('DTO validation errors').willEqual(0);
         });
 
-        await ifWe(sir, 'ensures data contains no functions or circular refs', async () => {
+        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).
 
@@ -978,4 +1086,453 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
         });
 
     });
+
+    await respecfully(sir, 'KeystoneProfileBuilder and Modular Schemas', async () => {
+
+        await ifWeMight(sir, 'compiles configs successfully with medium profile', async () => {
+            const builder = KeystoneProfileBuilder.buildKeystone('medium')
+                .withUsername('alice')
+                .withEmail('alice@example.com')
+                .withDescription('Alice test keystone')
+                .withDetails({ extraInfo: 'abc' });
+
+            const configs = await builder.compileConfigs();
+            iReckon(sir, configs.length).asTo('number of pools').willEqual(5);
+
+            // Verify unique salt derivation per pool
+            const salts = configs.map(c => c.salt);
+            const uniqueSalts = new Set(salts);
+            iReckon(sir, uniqueSalts.size).asTo('unique salts count').willEqual(5);
+
+            // Verify frameDetails unification
+            const details = builder.getFrameDetails();
+            iReckon(sir, details.username).asTo('username').willEqual('alice');
+            iReckon(sir, details.email).asTo('email').willEqual('alice@example.com');
+            iReckon(sir, details.description).asTo('description').willEqual('Alice test keystone');
+            iReckon(sir, details.extraInfo).asTo('extraInfo').willEqual('abc');
+        });
+
+        await ifWeMight(sir, 'supports customized overrides', async () => {
+            const builder = KeystoneProfileBuilder.buildKeystone('test')
+                .customizePool('sync', {
+                    behavior: {
+                        size: 15,
+                        targetBindingCount: 4
+                    }
+                });
+
+            const configs = await builder.compileConfigs();
+            const syncPool = configs.find(c => c.id === 'sync')!;
+            iReckon(sir, syncPool.behavior.size).asTo('customized size').willEqual(15);
+            iReckon(sir, syncPool.behavior.targetBindingCount).asTo('customized target binding').willEqual(4);
+        });
+
+    });
+
+    await respecfully(sir, 'Keystone Metadata Validation', async () => {
+
+        await ifWeMight(sir, 'validates correct username and description', async () => {
+            const service = new KeystoneService_V1();
+            const space = new MockIbGibSpace();
+            const metaspace = new MockMetaspaceService(space);
+
+            const builder = KeystoneProfileBuilder.buildKeystone('test')
+                .withUsername('alice_123.test')
+                .withDescription('Valid description: yes, it is!')
+                .withDetails({ client: 'respec' });
+
+            const configs = await builder.compileConfigs();
+            const frameDetails = builder.getFrameDetails();
+
+            // Should succeed without error
+            const keystoneIbGib = await service.genesis({
+                masterSecret: 'mysecret',
+                configs,
+                metaspace: metaspace as any,
+                space: space as any,
+                frameDetails
+            });
+
+            const errors = await service.validateGenesisKeystone({ keystoneIbGib });
+            iReckon(sir, errors.length).asTo('errors count').willEqual(0);
+        });
+
+        await ifWeMight(sir, 'fails validation for invalid username length or character', async () => {
+            const service = new KeystoneService_V1();
+            const space = new MockIbGibSpace();
+            const metaspace = new MockMetaspaceService(space);
+
+            const builder = KeystoneProfileBuilder.buildKeystone('test')
+                .withUsername('invalid_user_name_that_is_way_too_long_for_the_sixty_three_char_limit_and_will_fail_regex_check')
+                .withDetails({ client: 'respec' });
+
+            const configs = await builder.compileConfigs();
+            const frameDetails = builder.getFrameDetails();
+
+            const keystoneIbGib = await service.genesis({
+                masterSecret: 'mysecret',
+                configs,
+                metaspace: metaspace as any,
+                space: space as any,
+                frameDetails
+            });
+
+            const errors = await service.validateGenesisKeystone({ keystoneIbGib });
+            iReckon(sir, errors.length).asTo('errors count').willEqual(1);
+            iReckon(sir, errors[0]).includes('invalid username');
+        });
+
+        await ifWeMight(sir, 'fails validation for invalid description characters', async () => {
+            const service = new KeystoneService_V1();
+            const space = new MockIbGibSpace();
+            const metaspace = new MockMetaspaceService(space);
+
+            const builder = KeystoneProfileBuilder.buildKeystone('test')
+                .withUsername('alice')
+                .withDescription('Invalid desc with weird emoji 🚀')
+                .withDetails({ client: 'respec' });
+
+            const configs = await builder.compileConfigs();
+            const frameDetails = builder.getFrameDetails();
+
+            const keystoneIbGib = await service.genesis({
+                masterSecret: 'mysecret',
+                configs,
+                metaspace: metaspace as any,
+                space: space as any,
+                frameDetails
+            });
+
+            const errors = await service.validateGenesisKeystone({ keystoneIbGib });
+            iReckon(sir, errors.length).asTo('errors count').willEqual(1);
+            iReckon(sir, errors[0]).includes('invalid description');
+        });
+
+    });
+});
+
+
+// ===========================================================================
+// SUITE E: DELEGATION (Register/Unregister)
+// ===========================================================================
+
+await respecfully(sir, 'Suite E: Delegation (Register/Unregister)', async () => {
+
+    const service = new KeystoneService_V1();
+    const parentSecret = "ParentMasterSecret_123";
+    const delegateSecret = "DelegateMasterSecret_456";
+
+    let mockSpace: MockIbGibSpace;
+    let mockMetaspace: any;
+
+    let parentKeystone: KeystoneIbGib_V1;
+    let delegateKeystone: KeystoneIbGib_V1;
+
+    firstOfEach(sir, async () => {
+        mockSpace = new MockIbGibSpace();
+        mockMetaspace = new MockMetaspaceService(mockSpace);
+
+        const salt = (await getUUID()).substring(0, 16);
+        const defaultConfig = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt });
+        const manageConfig = createStandardPoolConfig({ id: POOL_ID_MANAGE, salt: salt + "_manage" });
+        manageConfig.allowedVerbs = [KEYSTONE_VERB_MANAGE];
+
+        // 1. Create Parent Keystone (with manage pool)
+        parentKeystone = await service.genesis({
+            masterSecret: parentSecret,
+            configs: [defaultConfig, manageConfig],
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        // 2. Create Delegate Keystone
+        const delegateConfig = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: salt + "_delegate" });
+        delegateKeystone = await service.genesis({
+            masterSecret: delegateSecret,
+            configs: [delegateConfig],
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+    });
+
+    await ifWeMight(sir, 'registers a delegate keystone and evolves parent using manage pool', async () => {
+        // Register the delegate
+        const evolvedParent = await service.registerDelegate({
+            parentKeystone,
+            delegateKeystone,
+            masterSecret: parentSecret,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        iReckon(sir, evolvedParent).asTo('evolved parent exists').isGonnaBeTruthy();
+        iReckon(sir, evolvedParent.data?.delegates).asTo('delegates map exists').isGonnaBeTruthy();
+
+        const delegateTjpAddr = getTjpAddr({ ibGib: delegateKeystone });
+        if (!delegateTjpAddr) { throw new Error(`(UNEXPECTED) delegateTjpAddr falsy? (E: 312e986ce4b2ed6c084c03e8f45fa826)`); }
+        const delegateInfo = evolvedParent.data?.delegates?.[delegateTjpAddr];
+        iReckon(sir, delegateInfo).asTo('delegate info registered').isGonnaBeTruthy();
+        iReckon(sir, delegateInfo?.delegateTjpAddr).asTo('delegate tjp matches').willEqual(delegateTjpAddr);
+    });
+
+    await ifWeMight(sir, 'gets correct delegate status via parent TJP address', async () => {
+        const parentTjpAddr = getTjpAddr({ ibGib: parentKeystone });
+        if (!parentTjpAddr) { throw new Error(`(UNEXPECTED) parentTjpAddr falsy? (E: b7ce2835ccd951d8c99257328be3b826)`); }
+        const delegateTjpAddr = getTjpAddr({ ibGib: delegateKeystone });
+        if (!delegateTjpAddr) { throw new Error(`(UNEXPECTED) delegateTjpAddr falsy? (E: 3e4878ea19dd8034e827466a8bf09526)`); }
+
+        // Before registration
+        const statusBefore = await service.getDelegateStatus({
+            parentTjpAddr: parentTjpAddr,
+            delegateTjpAddr: delegateTjpAddr,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+        iReckon(sir, statusBefore.registered).asTo('initially unregistered').isGonnaBeFalse();
+
+        // Register
+        const evolvedParent = await service.registerDelegate({
+            parentKeystone,
+            delegateKeystone,
+            masterSecret: parentSecret,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        // After registration
+        const statusAfter = await service.getDelegateStatus({
+            parentTjpAddr: parentTjpAddr,
+            delegateTjpAddr: delegateTjpAddr,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+        iReckon(sir, statusAfter.registered).asTo('registered status').isGonnaBeTrue();
+        iReckon(sir, statusAfter.delegateInfo?.delegateTjpAddr).asTo('status tjp matches').willEqual(delegateTjpAddr);
+    });
+
+    await ifWeMight(sir, 'unregisters a registered delegate keystone', async () => {
+        // Register first
+        const evolvedParent = await service.registerDelegate({
+            parentKeystone,
+            delegateKeystone,
+            masterSecret: parentSecret,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        const delegateTjpAddr = getTjpAddr({ ibGib: delegateKeystone });
+        if (!delegateTjpAddr) { throw new Error(`(UNEXPECTED) delegateTjpAddr falsy? (E: 486b486a8c984a52b8d2b22418c20d26)`); }
+
+        // Unregister
+        const finalParent = await service.unregisterDelegate({
+            parentKeystone: evolvedParent,
+            delegateTjpAddr,
+            masterSecret: parentSecret,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        iReckon(sir, finalParent).asTo('final evolved parent exists').isGonnaBeTruthy();
+        const info = finalParent.data?.delegates?.[delegateTjpAddr];
+        iReckon(sir, info).asTo('delegate info removed').isGonnaBeUndefined();
+    });
+
+    await ifWeMight(sir, 'throws if parent does not have a manage pool', async () => {
+        // Create a parent WITHOUT a manage pool
+        const salt = (await getUUID()).substring(0, 16);
+        const defaultConfig = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt });
+        const restrictedParent = await service.genesis({
+            masterSecret: parentSecret,
+            configs: [defaultConfig],
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        let errorCaught = false;
+        try {
+            await service.registerDelegate({
+                parentKeystone: restrictedParent,
+                delegateKeystone,
+                masterSecret: parentSecret,
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+        } catch (e: any) {
+            errorCaught = true;
+            iReckon(sir, e.message).includes('Manage pool is required');
+        }
+        iReckon(sir, errorCaught).asTo('delegation rejected').isGonnaBeTrue();
+    });
+});
+
+await respecfully(sir, 'Suite G: Delegate & IB Validation', async () => {
+    const service = new KeystoneService_V1();
+    const parentSecret = "ParentMasterSecret_SuiteG";
+    const delegateSecret = "DelegateMasterSecret_SuiteG";
+
+    let mockSpace: MockIbGibSpace;
+    let mockMetaspace: any;
+
+    let parentKeystone: KeystoneIbGib_V1;
+    let delegateKeystone: KeystoneIbGib_V1;
+
+    firstOfEach(sir, async () => {
+        mockSpace = new MockIbGibSpace();
+        mockMetaspace = new MockMetaspaceService(mockSpace);
+
+        const salt1 = (await getUUID()).substring(0, 16);
+        const salt2 = (await getUUID()).substring(0, 16);
+
+        const manageConfig = createStandardPoolConfig({ id: POOL_ID_MANAGE, salt: salt2 });
+        manageConfig.allowedVerbs = [KEYSTONE_VERB_MANAGE];
+
+        const configs = [
+            createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: salt1 }),
+            manageConfig
+        ];
+
+        parentKeystone = await service.genesis({
+            masterSecret: parentSecret,
+            configs,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        delegateKeystone = await service.genesis({
+            masterSecret: delegateSecret,
+            configs: [createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: salt1 })],
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+    });
+
+    await ifWeMight(sir, 'validateKeystoneIb returns true for valid keystone ib and false for others', async () => {
+        iReckon(sir, await validateKeystoneIb({ ib: 'keystone' })).isGonnaBeTrue();
+        iReckon(sir, await validateKeystoneIb({ ib: 'keystone user info' })).isGonnaBeTrue();
+        iReckon(sir, await validateKeystoneIb({ ib: 'invalidAtom' })).isGonnaBeFalse();
+        iReckon(sir, await validateKeystoneIb({ ib: 'not_keystone sub_atom' })).isGonnaBeFalse();
+    });
+
+    await ifWeMight(sir, 'validateGenesisKeystone fails validation if ib is invalid', async () => {
+        const invalidGenesis = {
+            ...parentKeystone,
+            ib: 'not_a_keystone^' + parentKeystone.gib,
+        };
+        const errors = await validateGenesisKeystone({ keystoneIbGib: invalidGenesis });
+        iReckon(sir, errors.length > 0).isGonnaBeTrue();
+        iReckon(sir, errors[0]).includes('invalid keystone ib');
+    });
+
+    await ifWeMight(sir, 'validateKeystoneTransition passes for valid delegate registration', async () => {
+        const evolvedParent = await service.registerDelegate({
+            parentKeystone,
+            delegateKeystone,
+            masterSecret: parentSecret,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        const errors = await validateKeystoneTransition({
+            currentIbGib: evolvedParent,
+            prevIbGib: parentKeystone,
+        });
+        iReckon(sir, errors.length).willEqual(0);
+    });
+
+    await ifWeMight(sir, 'validateKeystoneTransition fails if delegates map is mutated without manage proof', async () => {
+        const evolvedParent = await service.registerDelegate({
+            parentKeystone,
+            delegateKeystone,
+            masterSecret: parentSecret,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        const tamperedParent = JSON.parse(JSON.stringify(evolvedParent)) as KeystoneIbGib_V1;
+        
+        // Remove the manage verb proof by converting it to sign
+        for (const proof of tamperedParent.data.proofs) {
+            if (proof.claim) {
+                proof.claim.verb = 'sign';
+            }
+        }
+
+        const errors = await validateKeystoneTransition({
+            currentIbGib: tamperedParent,
+            prevIbGib: parentKeystone,
+        });
+        iReckon(sir, errors.length > 0).isGonnaBeTrue();
+        iReckon(sir, errors.some(e => e.includes('Policy Violation: Delegates map was mutated'))).isGonnaBeTrue();
+    });
+
+    await ifWeMight(sir, 'validateKeystoneTransition fails if delegate key does not match delegateTjpAddr', async () => {
+        const evolvedParent = await service.registerDelegate({
+            parentKeystone,
+            delegateKeystone,
+            masterSecret: parentSecret,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        const tamperedParent = JSON.parse(JSON.stringify(evolvedParent)) as KeystoneIbGib_V1;
+        const delegateTjpAddr = getTjpAddr({ ibGib: delegateKeystone });
+        if (!delegateTjpAddr) { throw new Error(`delegateTjpAddr falsy?`); }
+        
+        const info = tamperedParent.data.delegates![delegateTjpAddr];
+        delete tamperedParent.data.delegates![delegateTjpAddr];
+        tamperedParent.data.delegates!['mismatched_key'] = info;
+
+        const errors = await validateKeystoneTransition({
+            currentIbGib: tamperedParent,
+            prevIbGib: parentKeystone,
+        });
+        iReckon(sir, errors.length > 0).isGonnaBeTrue();
+        iReckon(sir, errors.some(e => e.includes('does not match delegateTjpAddr'))).isGonnaBeTrue();
+    });
+
+    await ifWeMight(sir, 'validateKeystoneTransition fails if delegate addresses have invalid keystone ib', async () => {
+        const evolvedParent = await service.registerDelegate({
+            parentKeystone,
+            delegateKeystone,
+            masterSecret: parentSecret,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        const tamperedParent = JSON.parse(JSON.stringify(evolvedParent)) as KeystoneIbGib_V1;
+        const delegateTjpAddr = getTjpAddr({ ibGib: delegateKeystone });
+        if (!delegateTjpAddr) { throw new Error(`delegateTjpAddr falsy?`); }
+
+        tamperedParent.data.delegates![delegateTjpAddr].delegateAddr = 'invalid_ib^12345';
+
+        const errors = await validateKeystoneTransition({
+            currentIbGib: tamperedParent,
+            prevIbGib: parentKeystone,
+        });
+        iReckon(sir, errors.length > 0).isGonnaBeTrue();
+        iReckon(sir, errors.some(e => e.includes('not a valid keystone address'))).isGonnaBeTrue();
+    });
+
+    await ifWeMight(sir, 'validateKeystoneTransition fails if thisAddr is not in the parent timeline history', async () => {
+        const evolvedParent = await service.registerDelegate({
+            parentKeystone,
+            delegateKeystone,
+            masterSecret: parentSecret,
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+
+        const tamperedParent = JSON.parse(JSON.stringify(evolvedParent)) as KeystoneIbGib_V1;
+        const delegateTjpAddr = getTjpAddr({ ibGib: delegateKeystone });
+        if (!delegateTjpAddr) { throw new Error(`delegateTjpAddr falsy?`); }
+
+        tamperedParent.data.delegates![delegateTjpAddr].thisAddr = 'keystone^randomgib';
+
+        const errors = await validateKeystoneTransition({
+            currentIbGib: tamperedParent,
+            prevIbGib: parentKeystone,
+        });
+        iReckon(sir, errors.length > 0).isGonnaBeTrue();
+        iReckon(sir, errors.some(e => e.includes('not a valid historical address in the parent keystone timeline'))).isGonnaBeTrue();
+    });
 });