@ibgib/core-gib 0.1.4 → 0.1.8

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

@@ -0,0 +1,611 @@
+import { extractErrorMsg, hash, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { mut8 } from '@ibgib/ts-gib/dist/V1/transforms/mut8.mjs';
+import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { getGib, getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../core-constants.mjs';
+import {
+    KeystoneData_V1,
+    KeystoneIbGib_V1,
+    KeystonePoolConfig,
+    KeystoneClaim,
+    KeystoneProof,
+    KeystoneChallengePool,
+    KeystoneSolution,
+    KeystoneReplenishStrategy,
+    KeystoneRevocationInfo,
+    KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES,
+} from './keystone-types.mjs';
+import { KeystoneStrategyFactory } from './strategy/keystone-strategy-factory.mjs';
+import { KEYSTONE_ATOM, POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE } from './keystone-constants.mjs';
+import {
+    addToBindingMap, getDeterministicRequirements, getKeystoneIb,
+    removeFromBindingMap,
+    validateKeystoneTransition,
+    verifyProofAgainstPool,
+} from './keystone-helpers.mjs';
+import { getDependencyGraph } from '../common/other/graph-helper.mjs';
+import { IbGibSpaceAny } from '../witness/space/space-base-v1.mjs';
+import { MetaspaceService } from '../witness/space/metaspace/metaspace-types.mjs';
+import { IbGibSpaceOptionsCmd } from '../witness/space/space-types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+/**
+ * Facade for managing Keystone Identities.
+ * 
+ * Handles Genesis, Authorized Evolution (Signing), and Validation.
+ */
+export class KeystoneService_V1 {
+    protected lc: string = `[${KeystoneService_V1.name}]`;
+
+    /**
+     * Creates a brand new Keystone Identity Timeline.
+     */
+    async genesis({
+        masterSecret,
+        configs,
+        metaspace,
+        space,
+    }: {
+        masterSecret: string;
+        configs: KeystonePoolConfig[];
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.genesis.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: c98ae8adbc5888dbf84c5aced7610b25)`); }
+
+            const challengePools: KeystoneChallengePool[] = [];
+
+            for (const config of configs) {
+                const strategy = KeystoneStrategyFactory.create({ config });
+                const poolSecret = await strategy.derivePoolSecret({ masterSecret });
+                const challenges: { [id: string]: any } = {};
+                const bindingMap: { [char: string]: string[] } = {};
+
+                const targetSize = config.behavior.size;
+                const timestamp = Date.now().toString();
+
+                for (let i = 0; i < targetSize; i++) {
+                    const challengeId = await this.generateOpaqueChallengeId({
+                        salt: config.salt, timestamp, index: i
+                    });
+
+                    const solution = await strategy.generateSolution({
+                        poolSecret, poolId: config.salt, challengeId,
+                    });
+                    const challenge = await strategy.generateChallenge({ solution });
+                    challenges[challengeId] = challenge;
+
+                    // Populate Binding Map
+                    addToBindingMap(bindingMap, challengeId);
+                }
+
+                challengePools.push({
+                    id: config.salt,
+                    config,
+                    challenges,
+                    bindingMap
+                });
+            }
+
+            const data: KeystoneData_V1 = { challengePools, proofs: [] };
+            const keystoneIbGib = await this.createKeystoneIbGibImpl({ data, metaspace, space });
+            return keystoneIbGib;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Signs a claim using a hybrid selection strategy.
+     * Supports: Mandatory IDs (Alice) + Sequential (FIFO) + Random (Stochastic).
+     */
+    async sign({
+        latestKeystone,
+        masterSecret,
+        claim,
+        poolId,
+        requiredChallengeIds = [],
+        frameDetails,
+        metaspace,
+        space,
+    }: {
+        latestKeystone: KeystoneIbGib_V1;
+        masterSecret: string;
+        claim: Partial<KeystoneClaim>;
+        poolId?: string;
+        requiredChallengeIds?: string[];
+        frameDetails?: any;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.sign.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 519e0810cce8647ce83bdb3b5019a825)`); }
+
+            const prevData = latestKeystone.data!;
+            if (prevData.revocationInfo) { throw new Error(`keystone has been revoked (latestKeystone.data.revocationInfo is truthy).  (E: 4f2198c39116d15c48ba191940316825)`); }
+
+            let pool: KeystoneChallengePool | undefined;
+            const poolsToSearch = prevData.challengePools;
+            if (logalot) { console.log(`${lc} Searching pools: ${poolsToSearch.map(p => p.id).join(', ')} for target: ${poolId || 'auto'}`); }
+
+            // ---------------------------------------------------------------
+            // 0. POOL RESOLUTION (Deterministic Mapping)
+            // ---------------------------------------------------------------
+            if (poolId) {
+                // Explicit selection
+                pool = poolsToSearch.find(p => p.id === poolId);
+                if (!pool) { throw new Error(`Pool not found: ${poolId} (E: genuuid)`); }
+
+                // Enforce Policy on Explicit Selection
+                // FIX: Check length > 0. If empty, it's a default pool (allow all).
+                if (pool.config.allowedVerbs && pool.config.allowedVerbs.length > 0 && claim.verb) {
+                    if (!pool.config.allowedVerbs.includes(claim.verb)) {
+                        throw new Error(`Pool ${poolId} is not authorized for verb: ${claim.verb} (E: genuuid)`);
+                    }
+                }
+            } else {
+                // Automatic Resolution based on Verb
+                if (!claim.verb) { throw new Error(`Cannot auto-resolve pool without a verb in the claim. (E: genuuid)`); }
+
+                // 1. Look for Specific Match
+                pool = poolsToSearch.find(p =>
+                    p.config.allowedVerbs && p.config.allowedVerbs.includes(claim.verb!)
+                );
+
+                // 2. Look for General/Default (No restrictions)
+                if (!pool) {
+                    pool = poolsToSearch.find(p =>
+                        !p.config.allowedVerbs || p.config.allowedVerbs.length === 0
+                    );
+                }
+
+                if (!pool) { throw new Error(`No suitable pool found for verb: ${claim.verb} (E: genuuid)`); }
+            }
+
+
+            // 1. Get Deterministic Requirements (Demands -> Binding -> FIFO)
+            const { mandatoryIds, availableIds } = getDeterministicRequirements({
+                pool,
+                requiredChallengeIds,
+                targetAddr: claim.target
+            });
+
+            // 2. Stochastic Selection
+            const randomCount = pool.config.behavior.selectRandomly;
+            const randomIds: string[] = [];
+
+            if (logalot) {
+                console.log(`${lc} Pool Info: id=${pool.id} invalid=${!pool} size=${Object.keys(pool.challenges || {}).length}`);
+                console.log(`${lc} Behavior: seq=${pool.config.behavior.selectSequentially} rand=${randomCount} binding=${pool.config.behavior.targetBindingChars}`);
+                console.log(`${lc} Requirements: mandatory=${mandatoryIds.size} available=${availableIds.length}`);
+            }
+
+            if (randomCount > 0) {
+                if (availableIds.length < randomCount) {
+                    throw new Error(`Insufficient challenges for random requirement. Need ${randomCount}, have ${availableIds.length}`);
+                }
+                // Shuffle & Pick
+                const shuffled = availableIds.sort(() => 0.5 - Math.random());
+                randomIds.push(...shuffled.slice(0, randomCount));
+            }
+
+            // 3. Combine & Solve
+            const finalSelectedIds = [...mandatoryIds, ...randomIds];
+
+            const strategy = KeystoneStrategyFactory.create({ config: pool.config });
+            const secretToUse = masterSecret;
+            const poolSecret = await strategy.derivePoolSecret({ masterSecret: secretToUse });
+            const solutions: KeystoneSolution[] = [];
+
+            for (const id of finalSelectedIds) {
+                const solution = await strategy.generateSolution({
+                    poolSecret, poolId: pool.id, challengeId: id,
+                });
+                solutions.push(solution);
+            }
+
+            // 4. Replenish
+            const nextPools = await this.applyReplenishmentStrategy({
+                prevPools: poolsToSearch,
+                targetPoolId: pool.id,
+                consumedIds: finalSelectedIds,
+                masterSecret: secretToUse,
+                strategy,
+                config: pool.config
+            });
+
+            // 5. Build Proof (Include requiredChallengeIds!)
+            const proof: KeystoneProof = {
+                claim,
+                solutions,
+                requiredChallengeIds: requiredChallengeIds.length > 0 ? requiredChallengeIds : undefined
+            };
+
+            const newData: KeystoneData_V1 = {
+                challengePools: nextPools,
+                proofs: [proof],
+                frameDetails,
+            };
+
+            const newIbGib = await this.evolveKeystoneIbGibImpl({ prevIbGib: latestKeystone, newData, metaspace, space });
+            return newIbGib;
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Validates a keystone.
+     * 
+     * ## NOTES
+     * 
+     * Atow (12/22/2025) this only validates the transition from Prev -> Curr.
+     * 
+     * @returns Array of validation error strings. Empty array means Valid.
+     * 
+     * @see {@link validateKeystoneTransition}
+     */
+    async validate({
+        currentIbGib,
+        prevIbGib,
+    }: {
+        currentIbGib: KeystoneIbGib_V1;
+        prevIbGib: KeystoneIbGib_V1;
+    }): Promise<string[]> {
+        // todo: change this to validate the entire keystone graph. the next
+        // step is to walk the history and validate each transition.
+        const errors = await validateKeystoneTransition({ currentIbGib, prevIbGib });
+        return errors;
+    }
+
+    /**
+     * Permanently revokes the Identity.
+     * 
+     * Logic:
+     * 1. Locates the 'revoke' pool.
+     * 2. Consumes ALL available challenges in that pool (Scorched Earth).
+     * 3. Sets the revocationInfo on the new frame.
+     */
+    async revoke({
+        latestKeystone,
+        masterSecret,
+        reason = "User initiated revocation",
+        frameDetails,
+        metaspace,
+        space,
+    }: {
+        latestKeystone: KeystoneIbGib_V1;
+        masterSecret: string;
+        reason?: string;
+        frameDetails?: any;
+        metaspace: MetaspaceService;
+        space?: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.revoke.name}]`;
+        try {
+            const prevData = latestKeystone.data!;
+            space ??= await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) { throw new Error(`(UNEXPECTED) space falsy and couldn't get default local user space from the metaspace? (E: 73c8bfc0e7383a540ea1d6b14b020125)`); }
+
+            // 1. Find Revocation Pool
+            const pool = prevData.challengePools.find(p => p.id === POOL_ID_REVOKE);
+            if (!pool) { throw new Error(`Revocation pool not found (E: 8c4f18c5461c1d601283108878c79825)`); }
+
+            // 2. Select Challenges (Standard Policy, NOT ALL)
+            const claim: Partial<KeystoneClaim> = {
+                verb: KEYSTONE_VERB_REVOKE,
+                target: getIbGibAddr({ ibGib: latestKeystone })
+            };
+
+            const { mandatoryIds, availableIds } = getDeterministicRequirements({
+                pool,
+                requiredChallengeIds: [], // Revocation usually doesn't have external demands
+                targetAddr: claim.target
+            });
+
+            // Stochastic Selection
+            const randomCount = pool.config.behavior.selectRandomly;
+            const randomIds: string[] = [];
+            if (randomCount > 0) {
+                if (availableIds.length < randomCount) { throw new Error(`Insufficient challenges. availableIds.length (${availableIds.length}) is less than required random count (${randomCount}) (E: b2e3570ab998dfdbab5fbdda1e43d825)`); }
+                const shuffled = availableIds.sort(() => 0.5 - Math.random());
+                randomIds.push(...shuffled.slice(0, randomCount));
+            }
+
+            const selectedIds = [...mandatoryIds, ...randomIds];
+            if (selectedIds.length === 0) { throw new Error(`Revocation policy selected 0 challenges? Check config for pool. id: ${pool.id}. pool.config: ${pretty(pool.config)} (E: 97e5a8356d241ae7b882db791cb1f825)`); }
+
+            // 3. Solve Selected
+            const strategy = KeystoneStrategyFactory.create({ config: pool.config });
+            const poolSecret = await strategy.derivePoolSecret({ masterSecret });
+            const solutions: KeystoneSolution[] = [];
+
+            for (const id of selectedIds) {
+                const solution = await strategy.generateSolution({
+                    poolSecret, poolId: pool.id, challengeId: id,
+                });
+                solutions.push(solution);
+            }
+
+            // 4. Replenish (Scorched Earth)
+            const nextPools = await this.applyReplenishmentStrategy({
+                prevPools: prevData.challengePools,
+                targetPoolId: pool.id,
+                consumedIds: selectedIds,
+                masterSecret,
+                strategy,
+                config: pool.config
+            });
+
+            // 5. Construct Proof
+            const proof: KeystoneProof = {
+                claim,
+                solutions,
+            };
+
+            const revocationInfo: KeystoneRevocationInfo = { reason, proof };
+
+            const newData: KeystoneData_V1 = {
+                challengePools: nextPools,
+                proofs: [proof],
+                revocationInfo,
+                frameDetails
+            };
+
+            return await this.evolveKeystoneIbGibImpl({
+                prevIbGib: latestKeystone,
+                newData,
+                metaspace,
+                space,
+            });
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Generates an opaque, collision-resistant ID for a challenge.
+     * atow (2025/12/22) - Hash(Salt + Timestamp + Index)
+     */
+    private async generateOpaqueChallengeId({
+        salt,
+        timestamp,
+        index
+    }: {
+        salt: string,
+        timestamp: string,
+        index: number
+    }): Promise<string> {
+        // Use full SHA-256 hash, or slice it?
+        // User suggested substring is fine for pool uniqueness.
+        // Let's use first 16 chars of hex (64 bits) for brevity + safety.
+        const raw = await hash({ s: `${salt}${timestamp}${index}` });
+        return raw.substring(0, 16);
+    }
+
+    private async applyReplenishmentStrategy({
+        prevPools,
+        targetPoolId,
+        consumedIds,
+        masterSecret,
+        strategy,
+        config
+    }: {
+        prevPools: KeystoneChallengePool[];
+        targetPoolId: string;
+        consumedIds: string[];
+        masterSecret: string;
+        strategy: any;
+        config: KeystonePoolConfig;
+    }): Promise<KeystoneChallengePool[]> {
+        const newPools = JSON.parse(JSON.stringify(prevPools));
+        if (logalot) { console.log(`[applyReplenishmentStrategy] Cloned pools. Ref check: ${prevPools === newPools} (should be false)`); }
+        const targetIdx = newPools.findIndex((p: any) => p.id === targetPoolId);
+        if (targetIdx === -1) { throw new Error(`Target pool ${targetPoolId} not found in keytstone data. (E: 75200388d22744838634524233772545)`); }
+        const pool = newPools[targetIdx];
+
+        const poolSecret = await strategy.derivePoolSecret({ masterSecret });
+        const timestamp = Date.now().toString();
+
+        const strategyType = config.behavior.replenish;
+
+        // Clean up Binding Map for consumed IDs
+        consumedIds.forEach(id => {
+            if (pool.bindingMap) { removeFromBindingMap(pool.bindingMap, id); }
+        });
+
+        if (strategyType === KeystoneReplenishStrategy.topUp) {
+            // Remove consumed
+            consumedIds.forEach(id => delete pool.challenges[id]);
+
+            // Add New
+            for (let i = 0; i < consumedIds.length; i++) {
+                const newId = await this.generateOpaqueChallengeId({
+                    salt: config.salt, timestamp, index: i
+                });
+
+                const solution = await strategy.generateSolution({
+                    poolSecret, poolId: pool.id, challengeId: newId
+                });
+                pool.challenges[newId] = await strategy.generateChallenge({ solution });
+
+                // Update Binding Map
+                if (!pool.bindingMap) { pool.bindingMap = {}; }
+                addToBindingMap(pool.bindingMap, newId);
+            }
+        } else if (strategyType === KeystoneReplenishStrategy.replaceAll) {
+            pool.challenges = {};
+            pool.bindingMap = {};
+
+            for (let i = 0; i < config.behavior.size; i++) {
+                const newId = await this.generateOpaqueChallengeId({
+                    salt: config.salt, timestamp, index: i
+                });
+                const solution = await strategy.generateSolution({
+                    poolSecret, poolId: pool.id, challengeId: newId
+                });
+                pool.challenges[newId] = await strategy.generateChallenge({ solution });
+                addToBindingMap(pool.bindingMap, newId);
+            }
+        } else if (strategyType === KeystoneReplenishStrategy.consume) {
+            consumedIds.forEach(id => delete pool.challenges[id]);
+        } else if (strategyType === KeystoneReplenishStrategy.scorchedEarth) {
+            pool.challenges = {};
+            pool.bindingMap = {};
+        } else {
+            throw new Error(`Unknown replenish strategy: ${strategyType}. Valid list: ${pretty(KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES)} (E: 0acf56f1e1486240080e11e8046d0825)`);
+        }
+
+        return newPools;
+    }
+
+    /**
+     * Creates a new keystone ibgib that has no dna and no past.
+     */
+    private async createKeystoneIbGibImpl({
+        data,
+        metaspace,
+        space,
+    }: {
+        data: KeystoneData_V1,
+        metaspace: MetaspaceService,
+        space?: IbGibSpaceAny,
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.createKeystoneIbGibImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 5e32389700e9899e788cbefacef7c825)`); }
+
+            space ??= await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) { throw new Error(`(UNEXPECTED) space was falsy and we couldn't get default local user space from metaspace? (E: 9a6498cf16a8801f19ec376749742225)`); }
+
+            // create the actual keystoneIbGib
+            const resFirstGen = await Factory_V1.firstGen({
+                parentIbGib: Factory_V1.primitive({ ib: KEYSTONE_ATOM }),
+                ib: await getKeystoneIb({ keystoneData: data }),
+                data,
+                dna: false,
+                nCounter: true,
+                tjp: {
+                    timestamp: true,
+                    uuid: true,
+                },
+            }) as TransformResult<KeystoneIbGib_V1>;
+            const keystoneIbGib = resFirstGen.newIbGib;
+
+            if (!keystoneIbGib.data) { throw new Error(`(UNEXPECTED) keystoneIbGib.data falsy? We expect the data to be populated with real keystone data. (E: 38a358facdb89d16d81d48c8520d3d25)`); }
+            if (!keystoneIbGib.rel8ns) { throw new Error(`(UNEXPECTED) keystoneIbGib.rel8ns falsy? we expect the rel8ns to have ancestor and past. (E: 20cb7723dc33ae1ef808fe76d1bf4b25)`); }
+            if (!keystoneIbGib.rel8ns.past || keystoneIbGib.rel8ns.past.length === 0) {
+                throw new Error(`(UNEXPECTED) keystoneIbGib.rel8ns.past falsy or empty? we expect the firstGen call to generate an interstitial ibgib that we will splice out. (E: 0fd8388d045ab9f37834c27d67e78825)`);
+            }
+
+            // reset n
+            keystoneIbGib.data.n = 0;
+            // reset tjp
+            keystoneIbGib.data.isTjp = true;
+            delete keystoneIbGib.rel8ns.tjp;
+            // reset past
+            delete keystoneIbGib.rel8ns.past;
+
+            // recalculate gib
+            keystoneIbGib.gib = await getGib({ ibGib: keystoneIbGib });
+
+            // save and register
+            await metaspace.put({ ibGib: keystoneIbGib, space, });
+            await metaspace.registerNewIbGib({ ibGib: keystoneIbGib, space, });
+
+            return keystoneIbGib;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    private async evolveKeystoneIbGibImpl({
+        prevIbGib,
+        newData,
+        metaspace,
+        space,
+    }: {
+        prevIbGib: KeystoneIbGib_V1,
+        newData: KeystoneData_V1
+        metaspace: MetaspaceService,
+        space: IbGibSpaceAny,
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.evolveKeystoneIbGibImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 8b10e8920f08b7842803665834cf8925)`); }
+
+            if (!prevIbGib.data) { throw new Error(`(UNEXPECTED) prevIbGib.data falsy? (E: 5e84875bf992c585b979e6c8ed5bf225)`); }
+            if (prevIbGib.data.revocationInfo) { throw new Error(`Keystone has already been revoked (prevIbGib.data.revocationInfo truthy), so we cannot evolve the keystone. Keystone addr: ${getIbGibAddr({ ibGib: prevIbGib })} (E: 45d7f846556829de6b2a701838c3f825)`); }
+
+            const prevData = prevIbGib.data;
+            /**
+             * we want to completely replace these keys, so we will remove them
+             * from the data. This occurs first in the underlying mut8
+             * transform.
+             * @see {@link mut8}
+             */
+            let dataToRemove: Partial<KeystoneData_V1> | undefined = {}
+            if (prevData.proofs) { dataToRemove.proofs = []; }
+            if (prevData.challengePools) { dataToRemove.challengePools = []; }
+            if (prevData.frameDetails) { dataToRemove.frameDetails = {}; }
+            if (Object.keys(dataToRemove).length === 0) { dataToRemove = undefined; }
+
+            const resMut8 = await mut8({
+                src: prevIbGib,
+                dataToRemove,
+                dataToAddOrPatch: newData,
+                // dna: false, // explicitly set to false just to show
+                nCounter: true,
+            });
+
+            if (!!resMut8.intermediateIbGibs) { throw new Error(`(UNEXPECTED) resMut8.intermediateIbGibs truthy? I'm not sure if we expect there to be intermediateIbGibs, but I feel like we shouldn't. Pretty sure we shouldn't, definitely don't *want* them. (E: ba40d55d7c2d36d438c413886f148625)`); }
+            if (!!resMut8.dnas) { throw new Error(`(UNEXPECTED) resMut8.dnas truthy? We do not want dnas with keystones. (E: 49470513d018f97d28024f4e82da3b25)`); }
+
+
+            const newKeystoneIbGib = resMut8.newIbGib as KeystoneIbGib_V1;
+
+            // run validation here
+            const errors = await this.validate({
+                currentIbGib: newKeystoneIbGib,
+                prevIbGib,
+            });
+            if (errors.length > 0) {
+                console.error(`${lc} Validation Failed:\n${errors.join('\n')}`);
+                throw new Error(`(UNEXPECTED) invalid keystone after we just evolved it? Errors: ${errors.join('; ')} (E: ae2c58406c1db7687879dfb89fc1f825)`);
+            }
+
+            // save and register
+            await metaspace.put({ ibGib: newKeystoneIbGib, space, });
+            await metaspace.registerNewIbGib({ ibGib: newKeystoneIbGib, space, });
+
+            return newKeystoneIbGib;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}