@ibgib/core-gib 0.1.8 → 0.1.10

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

@@ -1,36 +1,20 @@
-import { extractErrorMsg, hash, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { extractErrorMsg, } 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,
+    KeystoneData_V1, KeystoneIbGib_V1, KeystonePoolConfig, KeystoneClaim,
+    KeystoneChallengePool, KeystoneReplenishStrategy, KeystoneRevocationInfo,
 } 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 { POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE, KEYSTONE_VERB_MANAGE } from './keystone-constants.mjs';
 import {
-    addToBindingMap, getDeterministicRequirements, getKeystoneIb,
-    removeFromBindingMap,
-    validateKeystoneTransition,
-    verifyProofAgainstPool,
+    addToBindingMap, createKeystoneIbGibImpl, evolvePersistAndRegisterKeystone,
+    generateOpaqueChallengeId, resolveTargetPool, selectChallengeIds,
+    solveAndReplenish, validateKeystoneTransition,
 } 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;
 
@@ -72,7 +56,7 @@ export class KeystoneService_V1 {
                 const timestamp = Date.now().toString();
 
                 for (let i = 0; i < targetSize; i++) {
-                    const challengeId = await this.generateOpaqueChallengeId({
+                    const challengeId = await generateOpaqueChallengeId({
                         salt: config.salt, timestamp, index: i
                     });
 
@@ -94,8 +78,10 @@ export class KeystoneService_V1 {
                 });
             }
 
+            if (challengePools.length === 0) { throw new Error(`No challenge pools created. (E: 38e538530996940e1f16a8b199995825)`); }
+
             const data: KeystoneData_V1 = { challengePools, proofs: [] };
-            const keystoneIbGib = await this.createKeystoneIbGibImpl({ data, metaspace, space });
+            const keystoneIbGib = await createKeystoneIbGibImpl({ data, metaspace, space });
             return keystoneIbGib;
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -106,23 +92,41 @@ export class KeystoneService_V1 {
     }
 
     /**
-     * Signs a claim using a hybrid selection strategy.
-     * Supports: Mandatory IDs (Alice) + Sequential (FIFO) + Random (Stochastic).
+     * Signs a claim by solving challenges from a specific pool and evolving the Keystone timeline.
+     * 
+     * Uses a hybrid selection strategy: Mandatory IDs (Alice) + Sequential (FIFO) + Random (Stochastic).
+     * 
+     * Supports Delegation via `poolFilter` to find specific foreign pools.
      */
     async sign({
         latestKeystone,
         masterSecret,
         claim,
         poolId,
+        poolFilter,
         requiredChallengeIds = [],
         frameDetails,
         metaspace,
         space,
     }: {
         latestKeystone: KeystoneIbGib_V1;
+        /**
+         * The secret used to solve the challenges.
+         * If signing with a native pool, this is the User's Master Secret.
+         * If signing with a foreign/delegated pool, this is the Delegate's Secret.
+         */
         masterSecret: string;
         claim: Partial<KeystoneClaim>;
+        /**
+         * Explicit ID of the pool to use.
+         */
         poolId?: string;
+        /**
+         * Optional predicate to find a pool. 
+         * Useful for finding delegates via metadata without knowing the exact ID.
+         * e.g. (p) => p.metadata?.delegate === 'Bob'
+         */
+        poolFilter?: (pool: KeystoneChallengePool) => boolean;
         requiredChallengeIds?: string[];
         frameDetails?: any;
         metaspace: MetaspaceService;
@@ -130,117 +134,58 @@ export class KeystoneService_V1 {
     }): Promise<KeystoneIbGib_V1> {
         const lc = `${this.lc}[${this.sign.name}]`;
         try {
-            if (logalot) { console.log(`${lc} starting... (I: 519e0810cce8647ce83bdb3b5019a825)`); }
+            if (logalot) { console.log(`${lc} starting...`); }
 
             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)`); }
-            }
 
+            if (prevData.revocationInfo) { throw new Error(`Keystone has been revoked. Cannot sign. (E: 4f2198c39116d15c48ba191940316825)`); }
 
-            // 1. Get Deterministic Requirements (Demands -> Binding -> FIFO)
-            const { mandatoryIds, availableIds } = getDeterministicRequirements({
-                pool,
-                requiredChallengeIds,
-                targetAddr: claim.target
+            // 1. Identify Authority (Resolve Pool)
+            const pool = resolveTargetPool({
+                pools: prevData.challengePools,
+                poolId,
+                poolFilter,
+                verb: claim.verb
             });
 
-            // 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[] = [];
+            if (logalot) { console.log(`${lc} Selected pool: ${pool.id} (size: ${Object.keys(pool.challenges).length}) (I: genuuid)`); }
 
-            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
+            // 2. Calculate Costs (Select IDs)
+            const idsToSolve = selectChallengeIds({
+                pool,
+                targetAddr: claim.target,
+                requiredChallengeIds
             });
 
-            // 5. Build Proof (Include requiredChallengeIds!)
-            const proof: KeystoneProof = {
+            // 3. Pay the Cost (Solve & Replenish)
+            // This helper handles the Strategy creation, Secret derivation, Solving, 
+            // and the calculation of the Next state for ALL pools.
+            const { proof, nextPools } = await solveAndReplenish({
+                targetPoolId: pool.id,
+                prevPools: prevData.challengePools,
+                masterSecret,
+                challengeIds: idsToSolve,
                 claim,
-                solutions,
-                requiredChallengeIds: requiredChallengeIds.length > 0 ? requiredChallengeIds : undefined
-            };
+                requiredChallengeIds
+            });
 
+            // 4. Construct New Data
             const newData: KeystoneData_V1 = {
                 challengePools: nextPools,
                 proofs: [proof],
                 frameDetails,
+                // Revocation info is undefined for a standard sign operation
             };
 
-            const newIbGib = await this.evolveKeystoneIbGibImpl({ prevIbGib: latestKeystone, newData, metaspace, space });
-            return newIbGib;
+            // 5. Commit (Evolve, Persist, Register)
+            const resKeystone = await evolvePersistAndRegisterKeystone({
+                prevIbGib: latestKeystone,
+                newData,
+                metaspace,
+                space
+            });
 
+            return resKeystone;
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;
@@ -278,8 +223,9 @@ export class KeystoneService_V1 {
      * 
      * Logic:
      * 1. Locates the 'revoke' pool.
-     * 2. Consumes ALL available challenges in that pool (Scorched Earth).
-     * 3. Sets the revocationInfo on the new frame.
+     * 2. Solves required challenges to prove ownership.
+     * 3. Wipes the pool (via 'scorched-earth' strategy in solveAndReplenish).
+     * 4. Sets the revocationInfo on the new frame.
      */
     async revoke({
         latestKeystone,
@@ -294,72 +240,56 @@ export class KeystoneService_V1 {
         reason?: string;
         frameDetails?: any;
         metaspace: MetaspaceService;
-        space?: IbGibSpaceAny;
+        space: IbGibSpaceAny;
     }): Promise<KeystoneIbGib_V1> {
         const lc = `${this.lc}[${this.revoke.name}]`;
         try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
             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)`); }
+            // 1. Identify Authority (Resolve Revoke Pool)
+            const pool = resolveTargetPool({
+                pools: prevData.challengePools,
+                poolId: POOL_ID_REVOKE // Explicitly require the special revoke pool
+            });
 
-            // 2. Select Challenges (Standard Policy, NOT ALL)
+            // 2. Construct Claim
             const claim: Partial<KeystoneClaim> = {
                 verb: KEYSTONE_VERB_REVOKE,
                 target: getIbGibAddr({ ibGib: latestKeystone })
             };
 
-            const { mandatoryIds, availableIds } = getDeterministicRequirements({
+            // 3. Calculate Costs
+            const idsToSolve = selectChallengeIds({
                 pool,
-                requiredChallengeIds: [], // Revocation usually doesn't have external demands
-                targetAddr: claim.target
+                targetAddr: claim.target,
+                requiredChallengeIds: []
             });
 
-            // 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));
-            }
+            if (idsToSolve.length === 0) { throw new Error(`Revocation policy selected 0 challenges? Check config for pool ${pool.id}. Revocation requires proof. (E: 97e5a8356d241ae7b882db791cb1f825)`); }
 
-            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,
+            // 4. Pay the Cost & Scorched Earth
+            // The revoke pool config should have 'replenish: scorched-earth', 
+            // causing solveAndReplenish to return an empty pool in nextPools.
+            const { proof, nextPools } = await solveAndReplenish({
                 targetPoolId: pool.id,
-                consumedIds: selectedIds,
+                prevPools: prevData.challengePools,
                 masterSecret,
-                strategy,
-                config: pool.config
-            });
-
-            // 5. Construct Proof
-            const proof: KeystoneProof = {
+                challengeIds: idsToSolve,
                 claim,
-                solutions,
-            };
+                requiredChallengeIds: []
+            });
+            // warn if nextPools contains pool.id that isn't empty (we were
+            // supposed to do "scorched earth" which empties the pool)
+            if (nextPools.find(p => p.id === pool.id && Object.keys(p.challenges).length > 0)) {
+                console.warn(`${lc} revocation pool ${pool.id} is not empty after revocation. Is the revocation pool replenish strategy set to ${KeystoneReplenishStrategy.scorchedEarth}? (W: 300c28bc8b98fc3e3c0b0d988344f825)`);
+            }
 
+            // 5. Construct Revocation Info
             const revocationInfo: KeystoneRevocationInfo = { reason, proof };
 
+            // 6. Construct New Data
             const newData: KeystoneData_V1 = {
                 challengePools: nextPools,
                 proofs: [proof],
@@ -367,13 +297,15 @@ export class KeystoneService_V1 {
                 frameDetails
             };
 
-            return await this.evolveKeystoneIbGibImpl({
+            // 7. Commit
+            const newKeystone = await evolvePersistAndRegisterKeystone({
                 prevIbGib: latestKeystone,
                 newData,
                 metaspace,
-                space,
+                space
             });
 
+            return newKeystone;
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;
@@ -383,224 +315,108 @@ export class KeystoneService_V1 {
     }
 
     /**
-     * Generates an opaque, collision-resistant ID for a challenge.
-     * atow (2025/12/22) - Hash(Salt + Timestamp + Index)
+     * Structural evolution: Adds new challenge pools to the keystone.
+     * 
+     * Use Case: Adding a delegate (Server) for SSO, adding a recovery key, 
+     * or rotating to a new set of pools.
+     * 
+     * Requires the Master Secret to authorize the change via a pool containing 
+     * the 'manage' verb.
      */
-    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,
+    async addPools({
+        latestKeystone,
         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,
+        newPools,
         metaspace,
         space,
     }: {
-        data: KeystoneData_V1,
-        metaspace: MetaspaceService,
-        space?: IbGibSpaceAny,
+        latestKeystone: KeystoneIbGib_V1;
+        /**
+         * Alice's Master Secret. 
+         * Required to solve challenges from the Admin/Manage pool to authorize this change.
+         */
+        masterSecret: string;
+        /**
+         * The pools to add. 
+         * NOTE: These are fully constructed Pool objects. 
+         * If they are foreign (Bob's), Alice must have constructed them 
+         * using Bob's challenges + Her config restrictions + isForeign=true.
+         */
+        newPools: KeystoneChallengePool[];
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
     }): Promise<KeystoneIbGib_V1> {
-        const lc = `${this.lc}[${this.createKeystoneIbGibImpl.name}]`;
+        const lc = `${this.lc}[${this.addPools.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;
+            if (logalot) { console.log(`${lc} starting...`); }
 
-            // recalculate gib
-            keystoneIbGib.gib = await getGib({ ibGib: keystoneIbGib });
+            if (!latestKeystone.data) { throw new Error(`(UNEXPECTED) latestKeystone.data falsy? (E: 7334c8faed128166a999d428c7805b25)`); }
+            const prevData = latestKeystone.data;
 
-            // save and register
-            await metaspace.put({ ibGib: keystoneIbGib, space, });
-            await metaspace.registerNewIbGib({ ibGib: keystoneIbGib, space, });
+            if (prevData.revocationInfo) { throw new Error(`Keystone has been revoked. Cannot add pools. (E: 8599f8f51c78d722252ddb2894fdbe25)`); }
 
-            return keystoneIbGib;
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
+            if (newPools.length === 0) { throw new Error(`No new pools provided to add. (E: 6599f8f51c78d722252ddb2894fdbe25)`); }
 
-    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,
+            // 1. Identify Authority (Resolve Admin Pool)
+            // We need a pool that allows the 'manage' verb.
+            const adminPool = resolveTargetPool({
+                pools: prevData.challengePools,
+                verb: KEYSTONE_VERB_MANAGE,
             });
 
-            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)`); }
+            if (logalot) { console.log(`${lc} Authorized via pool: ${adminPool.id}`); }
 
+            // 2. Construct the Management Claim
+            const target = getIbGibAddr({ ibGib: latestKeystone });
+            const claim: Partial<KeystoneClaim> = {
+                verb: KEYSTONE_VERB_MANAGE,
+                target, // I am managing myself
+                // Scope creates a cryptographic commitment to WHICH pools are being added
+                scope: JSON.stringify({ add: newPools.map(p => p.id) })
+            };
 
-            const newKeystoneIbGib = resMut8.newIbGib as KeystoneIbGib_V1;
+            // 3. Calculate Costs
+            const idsToSolve = selectChallengeIds({
+                pool: adminPool,
+                targetAddr: target
+            });
 
-            // run validation here
-            const errors = await this.validate({
-                currentIbGib: newKeystoneIbGib,
-                prevIbGib,
+            // 4. Pay the Cost (Solve & Replenish)
+            // This authorizes the change by evolving the admin pool.
+            const { proof, nextPools: replenishedExistingPools } = await solveAndReplenish({
+                targetPoolId: adminPool.id,
+                prevPools: prevData.challengePools,
+                masterSecret,
+                challengeIds: idsToSolve,
+                claim,
             });
-            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)`);
+
+            // 5. Mutate Structure (Add the new pools)
+            // We verify ID uniqueness cheaply here to prevent blatant errors
+            const existingIds = new Set(replenishedExistingPools.map(p => p.id));
+            for (const newPool of newPools) {
+                if (existingIds.has(newPool.id)) {
+                    throw new Error(`Cannot add pool. ID collision: ${newPool.id} (E: 8a4c2b1d3e5f6a7b8c9d0e1f2a3b4c5d)`);
+                }
             }
 
-            // save and register
-            await metaspace.put({ ibGib: newKeystoneIbGib, space, });
-            await metaspace.registerNewIbGib({ ibGib: newKeystoneIbGib, space, });
+            const finalPools = [...replenishedExistingPools, ...newPools];
+
+            // 6. Construct New Data
+            const newData: KeystoneData_V1 = {
+                challengePools: finalPools,
+                proofs: [proof], // The proof authorizes the structure change
+            };
+
+            // 7. Commit
+            const newKeystone = await evolvePersistAndRegisterKeystone({
+                prevIbGib: latestKeystone,
+                newData,
+                metaspace,
+                space
+            });
 
-            return newKeystoneIbGib;
+            return newKeystone;
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;