@ibgib/core-gib 0.1.45 → 0.1.48

package/src/keystone/keystone-helpers.mts

@@ -1,4 +1,4 @@
-import { extractErrorMsg, hash, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { extractErrorMsg, hash, HashAlgorithm, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
 import { GIB } from "@ibgib/ts-gib/dist/V1/constants.mjs";
 import { Ib, TransformResult } from "@ibgib/ts-gib/dist/types.mjs";
 import { getIbAndGib, getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
@@ -8,18 +8,23 @@ import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
 import { getGib } from "@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs";
 
 import { GLOBAL_LOG_A_LOT } from "../core-constants.mjs";
-import { KEYSTONE_ATOM } from "./keystone-constants.mjs";
+import { KEYSTONE_ATOM, KEYSTONE_HASH_MAX_ROUNDS, KEYSTONE_POOL_ID_REGEXP, KEYSTONE_SALT_REGEXP } from "./keystone-constants.mjs";
 import {
     KeystoneData_V1, KeystoneIbGib_V1, KeystoneIb_V1, KeystoneChallengePool,
     DeterministicResult, KeystoneProof, KeystonePoolConfig,
     KeystoneReplenishStrategy, KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES,
     KeystoneClaim, KeystoneSolution,
+    KeystoneChallengeType,
+    KEYSTONE_CHALLENGE_TYPE_VALID_VALUES,
+    KeystonePoolConfig_HashV1,
 } from "./keystone-types.mjs";
 import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
 import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
 import { KeystoneStrategyFactory } from "./strategy/keystone-strategy-factory.mjs";
 import { getDependencyGraph } from "../common/other/graph-helper.mjs";
-import { getTimelinesGroupedByTjp, splitPerTjpAndOrDna } from "../common/other/ibgib-helper.mjs";
+import { getIbGibsFromCache_fallbackToSpaces, getTimelinesGroupedByTjp, splitPerTjpAndOrDna } from "../common/other/ibgib-helper.mjs";
+import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { getLatestAddrs } from "../witness/space/space-helper.mjs";
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -184,12 +189,14 @@ export function addToBindingMap(
     const firstChar = challengeId.charAt(0).toLowerCase();
     // Validate it is hex
     if (/[0-9a-f]/.test(firstChar)) {
-        if (!map[firstChar]) map[firstChar] = [];
+        if (!map[firstChar]) { map[firstChar] = []; }
         map[firstChar].push(challengeId);
 
         // OPTIONAL: Implement Full Coverage Strategy here?
         // e.g. map[challengeId[1]].push(challengeId) ...
         // For V1, we stick to Native/Implicit bucket (Index 0).
+    } else {
+        throw new Error(`invalid challengeId (${challengeId}). Must start with a hex character. (E: c96ed8460de89e28c801370a0f07f826)`);
     }
 }
 
@@ -519,6 +526,156 @@ export async function solveAndReplenish({
     }
 }
 
+export async function validateChallengePool_typeHashRevealV1({ pool }: {
+    pool: KeystoneChallengePool;
+}): Promise<string[]> {
+    const lc = `[${validateChallengePool_typeHashRevealV1.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: e2ffd568b698cc12d8c5e838d73ae726)`); }
+
+        if (!pool.config) { throw new Error(`(UNEXPECTED) pool.configy falsy? (E: fcde88fe20e8004a58d7e445436bf526)`); }
+        if (pool.config.type !== KeystoneChallengeType.hash_reveal_v1) {
+            throw new Error(`(UNEXPECTED) pool.config.type !== KeystoneChallengeType.hash_reveal_v1? (E: e205f8872909c37168a624a9df778c26)`);
+        }
+
+        const errors: string[] = [];
+
+        const { algo, rounds, salt, } = pool.config as KeystonePoolConfig_HashV1;
+
+        const validAlgos: HashAlgorithm[] = [HashAlgorithm.sha_256];
+        if (algo) {
+            if (!validAlgos.includes(algo)) {
+                errors.push(`${lc} invalid hash algorithm (${algo}). Must be one of ${validAlgos}. (E: a22399ca3a68e63ffcc7507699be5826)`);
+            }
+        } else {
+            errors.push(`${lc} algorithm required. (E: 8cd6bfb0590862b9bae24d98d2cf3826)`)
+        }
+
+        if (rounds && typeof rounds === 'number' && Number.isInteger(rounds)) {
+            if (rounds > KEYSTONE_HASH_MAX_ROUNDS) {
+                errors.push(`${lc} rounds too high. max rounds: ${KEYSTONE_HASH_MAX_ROUNDS} (E: 31ce082f7fd88d6b58ef08a816458826)`);
+            }
+        } else {
+            errors.push(`${lc} invalid rounds (${rounds}). must be positive integer. (E: 73c643ccda78afaf28d52a6871a9e826)`);
+        }
+
+        if (salt && typeof salt === 'string') {
+            // no limits on this? sanity check?
+            if (!KEYSTONE_SALT_REGEXP.test(salt)) {
+                errors.push(`${lc} invalid salt (${salt.substring(0, 99)}). Must match regexp ${KEYSTONE_SALT_REGEXP}`);
+            }
+        } else {
+            errors.push(`${lc} invalid salt (${salt}). must be truthy string value. (E: 564a4844ec88fc1988197ce89c381426)`);
+        }
+
+        return errors;
+
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+export async function validateChallengePool({ pool }: {
+    pool: KeystoneChallengePool;
+}): Promise<string[]> {
+    const lc = `[${validateChallengePool.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 1a0eafc158a83d1ba8fc019d5c979a26)`); }
+        const errors: string[] = [];
+
+        if (pool.config) {
+            // first validate common to all pools, regardless of type...
+            if (pool.config.id) {
+                if (!KEYSTONE_POOL_ID_REGEXP.test(pool.config.id)) {
+                    // not 100% that this is needed but hey
+                    errors.push(`${lc} pool.config.id is not formatted correctly. must pass regexp: ${KEYSTONE_POOL_ID_REGEXP.source}`);
+                }
+            } else {
+                errors.push(`${lc} pool.config.id falsy (E: 31d7943d95f877326d5f4ea14463d626)`);
+            }
+
+            if (pool.config.behavior) {
+                const { size } = pool.config.behavior;
+                if (!size || size === 0) {
+                    errors.push(`${lc} invalid pool.config.behavior.size (${size}). Must be positive integer. (E: b221e36ec102bdc944552248ce8fe626)`)
+                }
+                // todo: more behavior checks
+            } else {
+                errors.push(`${lc} pool.config.behavior falsy (E: bede081c066c39732eefe2f92e296326)`)
+            }
+
+            // ...then do type-specific validation
+            const poolType = pool.config.type;
+            switch (poolType) {
+                case KeystoneChallengeType.hash_reveal_v1:
+                    const errorsHashRevealV1 = await validateChallengePool_typeHashRevealV1({ pool });
+                    errorsHashRevealV1.forEach(x => errors.push(x));
+                    break;
+                default:
+                    throw new Error(`(UNEXPECTED) unknown pool.config.type (${poolType})? We only implement the following at this time: ${KEYSTONE_CHALLENGE_TYPE_VALID_VALUES} (E: cce5285cf7580b8bc82172488eba2826)`);
+            }
+        } else {
+            errors.push(`${lc} pool.config falsy. (E: 8d05c875a1d2c58018a5eaf803977d26)`);
+        }
+
+        return errors;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+
+export async function validateGenesisKeystone({
+    keystoneIbGib
+}: {
+    keystoneIbGib: KeystoneIbGib_V1;
+}): Promise<string[]> {
+    const lc = `[${validateGenesisKeystone.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: ec6ba82ec848b5ac3d8953e89d8d9826)`); }
+
+        const errors: string[] = [];
+
+        const { data, rel8ns } = keystoneIbGib;
+
+        // no proofs/solutions yet
+        if (data.proofs && data.proofs.length > 0) {
+            errors.push(`${lc} proofs already exist on genesis keystone. (E: 7a5e15f20918f1bbd8ffb62857dcd526)`);
+        }
+
+        for (const pool of data.challengePools) {
+            // validate each pool intrinsically (config, sanity)
+            const poolErrors = await validateChallengePool({ pool });
+            poolErrors.forEach(x => errors.push(x));
+
+            //  additionally ensure each pool has challenges. This is only on
+            //  this genesis keystone, as it is valid to have pool without
+            //  challenges after revocation
+            if (!pool.challenges || Object.keys(pool.challenges).length === 0) {
+                errors.push(`${lc} invalid pool (${pool.id}). pool.challenges is falsy/empty. (E: 8cd16a5416ae62a058342828be465b26)`);
+            }
+        }
+
+        // not stated as revoked already
+        if (!!data.revocationInfo) {
+            errors.push(`${lc} genesis keystone already has revocationInfo. (E: e11408d0c558d0fa948efbce611ec826)`);
+        }
+
+        return errors;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
 /**
  * Validates the transition from Prev -> Curr.
  * Enforces Cryptography AND Behavioral Policy.
@@ -793,9 +950,17 @@ export async function createKeystoneIbGibImpl({
 
 export async function validateKeystoneGraph({
     keystoneIbGib,
+    getLatest,
+    invalidIfMoreRecentKeystoneFoundInSpace,
     space,
 }: {
     keystoneIbGib: KeystoneIbGib_V1,
+    /**
+     * if true, then this will get the latest keystone known in the incoming
+     * {@link keystoneIbGib} timeline, as found in {@link space}.
+     */
+    getLatest: boolean,
+    invalidIfMoreRecentKeystoneFoundInSpace: boolean,
     space: IbGibSpaceAny,
 }): Promise<string[]> {
     const lc = `[${validateKeystoneGraph.name}]`;
@@ -807,6 +972,44 @@ export async function validateKeystoneGraph({
 
         const errors: string[] = [];
 
+        // first, get the latest if that is the case...
+        if (getLatest) {
+            const keystoneAddr = getIbGibAddr({ ibGib: keystoneIbGib });
+            const resGetLatestAddrs = await getLatestAddrs({
+                ibGibs: [keystoneIbGib],
+                space,
+            });
+            if (!resGetLatestAddrs.data) { throw new Error(`(UNEXPECTED) resGetLatestAddrs.data falsy? (E: 3a23b3b420a8da1928219ca8d47b2126)`); }
+            if (!resGetLatestAddrs.data.latestAddrsMap) { throw new Error(`(UNEXPECTED) resGetLatestAddrs.data.latestAddrsMap falsy? (E: 93f1180598fb65a4b8d36e08d6c50426)`); }
+
+            const { latestAddrsMap } = resGetLatestAddrs.data;
+            if (Object.keys(latestAddrsMap).length === 0) {
+                throw new Error(`(UNEXPECTED) latestAddrsMap truthy but empty? (E: 7142f8f7625b9186281d08251e407826)`);
+            }
+
+            const latestAddr = latestAddrsMap[keystoneAddr];
+            if (latestAddr) {
+                if (latestAddr !== keystoneAddr) {
+                    if (invalidIfMoreRecentKeystoneFoundInSpace) {
+                        errors.push(`${lc} more recent keystone (${latestAddr}) found than the one passed in (${keystoneAddr}) in space (${space.ib}). (E: 64bf48de9448ee5c7528bf03bed2a826)`);
+                    } else {
+                        // get the latest ibgib and point the incoming ref to that
+                        const [latestKeystoneIbGib] = await getIbGibsFromCache_fallbackToSpaces({
+                            addrs: [latestAddr],
+                            space,
+                        });
+                        keystoneIbGib = latestKeystoneIbGib as KeystoneIbGib_V1;
+                    }
+                } else {
+                    // the incoming ibgib **is** the latest keystone, so nothing more to be done.
+                    if (logalot) { console.log(`${lc} incoming keystone (${keystoneAddr}) is the latest in the space (${space.ib}) (I: 8ffbd8d6cbc8a461e5e7f1084bd22a26)`); }
+                }
+            } else {
+                // keystone not found in space?
+                console.warn(`${lc} keystoneIbGib (${keystoneAddr}) not found in space (${space.ib}). I don't know what the implications of this are. (W: 258c88742448db34a585669484771826)`)
+            }
+        }
+
         const dependencyGraph = await getDependencyGraph({
             ibGib: keystoneIbGib,
             space,
@@ -840,14 +1043,39 @@ export async function validateKeystoneGraph({
             const keys = Object.keys(orderedKeystonesMap);
             if (keys.length === 0) {
                 throw new Error(`(UNEXPECTED) orderedKeystonesMap empty? (E: d437b80bef58e83a034b28af46278726)`);
-            } else if (keys.length > 0) {
-                // keys.length > 0
+            } else if (keys.length > 1) {
+                // keys.length > 1
                 throw new Error(`(UNEXPECTED) more than one timeline in keystone graph? ATOW (02/19/2026) we are expecting only a single timeline. (E: 66085b14e3887a59c872afd240511f26)`);
             }
             // happy path: exactly one timeline
             const keystoneTjpAddr = keys[0];
-            const keystoneIbGibs_ordered = orderedKeystonesMap[keystoneTjpAddr];
+            const keystoneIbGibs_ordered = orderedKeystonesMap[keystoneTjpAddr] as KeystoneIbGib_V1[];
+
+            if (keystoneIbGibs_ordered.length === 0) { throw new Error(`(UNEXPECTED) empty keystoneIbGibs_ordered? (E: 4a6b085aa8a76828a8d65367e7e56526)`); }
+
+            const genesisErrors = await validateGenesisKeystone({
+                keystoneIbGib: keystoneIbGibs_ordered[0]
+            });
+            genesisErrors.forEach(x => errors.push(x));
 
+            if (keystoneIbGibs_ordered.length === 1) {
+                // only the genesis keystone, which has already been done.
+            } else {
+                // more than 1 keystone, so validate the transitions
+                for (let i = 0; i < keystoneIbGibs_ordered.length - 1; i++) {
+                    const prevIbGib = keystoneIbGibs_ordered[i];
+                    const currentIbGib = keystoneIbGibs_ordered[i + 1];
+                    const transitionErrors = await validateKeystoneTransition({
+                        prevIbGib, currentIbGib
+                    });
+                    if (transitionErrors.length > 0) {
+                        errors.push(`${lc} keystone has ${transitionErrors.length} transition errors. i: ${i}. prevIbGib addr: ${getIbGibAddr({ ibGib: prevIbGib })}. currentIbGib addr: ${getIbGibAddr({ ibGib: currentIbGib })}. (E: 3ac17be916141d0c286ca5a87bb1b426)`);
+                        transitionErrors.forEach(x => errors.push(x));
+                    }
+
+                    break; // stop after the first found transition error
+                }
+            }
         } else {
             // one of the other errors regarding mapWithTjp_YesDna or
             // mapWithoutTjps will exist at this point, so we don't need to add
@@ -863,4 +1091,5 @@ export async function validateKeystoneGraph({
     } finally {
         if (logalot) { console.log(`${lc} complete.`); }
     }
-}
+}
+

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

@@ -31,11 +31,13 @@ export class KeystoneService_V1 {
      */
     async genesis({
         masterSecret,
+        frameDetails,
         configs,
         metaspace,
         space,
     }: {
         masterSecret: string;
+        frameDetails?: any;
         configs: KeystonePoolConfig[];
         metaspace: MetaspaceService;
         space: IbGibSpaceAny;
@@ -81,6 +83,7 @@ export class KeystoneService_V1 {
             if (challengePools.length === 0) { throw new Error(`No challenge pools created. (E: 38e538530996940e1f16a8b199995825)`); }
 
             const data: KeystoneData_V1 = { challengePools, proofs: [] };
+            if (frameDetails) { data.frameDetails = frameDetails; }
             const keystoneIbGib = await createKeystoneIbGibImpl({ data, metaspace, space });
             return keystoneIbGib;
         } catch (error) {
@@ -97,6 +100,8 @@ export class KeystoneService_V1 {
      * Uses a hybrid selection strategy: Mandatory IDs (Alice) + Sequential (FIFO) + Random (Stochastic).
      *
      * Supports Delegation via `poolFilter` to find specific foreign pools.
+     *
+     * todo: wrap this and other entire keystone sign/method implementations in locks on the keystone's tjpGib.
      */
     async sign({
         latestKeystone,

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

@@ -203,7 +203,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Derivation Logic', async () => {
 
-        await ifWeMight(sir, 'derivePoolSecret with same inputs returns same output', async () => {
+        await ifWe(sir, 'derivePoolSecret with same inputs returns same output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -213,7 +213,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secret length').isGonnaBeTruthy();
         });
 
-        await ifWeMight(sir, 'derivePoolSecret with different master secret returns different output', async () => {
+        await ifWe(sir, 'derivePoolSecret with different master secret returns different output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -222,7 +222,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secrets differ').not.willEqual(secretB);
         });
 
-        await ifWeMight(sir, 'derivePoolSecret with different salt returns different output', async () => {
+        await ifWe(sir, 'derivePoolSecret with different salt returns different output', async () => {
             // Modify salt in a copy of config
             const configB = { ...config, salt: "OtherPool" };
             const strategyA = KeystoneStrategyFactory.create({ config });
@@ -237,7 +237,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Challenge/Solution Logic', async () => {
 
-        await ifWeMight(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
+        await ifWe(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "a3ff7843552870fc28bef2b"; // arbitrary random challengeId
@@ -256,7 +256,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('valid pair should pass').isGonnaBeTrue();
         });
 
-        await ifWeMight(sir, 'validateSolution fails for mismatched values', async () => {
+        await ifWe(sir, 'validateSolution fails for mismatched values', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "8c994f3ed598f150e25513"; // arbitrary random challengeId
@@ -272,7 +272,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('tampered solution should fail').isGonnaBeFalse();
         });
 
-        await ifWeMight(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
+        await ifWe(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
 
@@ -313,7 +313,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Genesis', async () => {
-        await ifWeMight(sir, 'creates a valid genesis frame and persists it', async () => {
+        await ifWe(sir, 'creates a valid genesis frame and persists it', async () => {
             const config = createStandardPoolConfig({
                 id: POOL_ID_DEFAULT,
                 salt: POOL_ID_DEFAULT,
@@ -344,7 +344,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Signing (Evolution)', async () => {
-        await ifWeMight(sir, 'evolves the keystone with a valid proof', async () => {
+        await ifWe(sir, 'evolves the keystone with a valid proof', async () => {
             const claim: Partial<KeystoneClaim> = {
                 target: "comment 123^gib",
                 verb: "post"
@@ -374,7 +374,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Validation', async () => {
-        await ifWeMight(sir, 'validates the genesis->signed transition', async () => {
+        await ifWe(sir, 'validates the genesis->signed transition', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: signedKeystone,
@@ -422,7 +422,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Wrong Secret (Forgery)', async () => {
-        await ifWeMight(sir, 'prevents creation of forged frames', async () => {
+        await ifWe(sir, 'prevents creation of forged frames', async () => {
             const claim: Partial<KeystoneClaim> = { target: "comment 123^gib", verb: "post" };
 
             let errorCaught = false;
@@ -451,7 +451,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Policy Violation (Restricted Verbs)', async () => {
-        await ifWeMight(sir, 'throws error if signing forbidden verb with restricted pool', async () => {
+        await ifWe(sir, 'throws error if signing forbidden verb with restricted pool', async () => {
             // Create a specific restricted pool config manually
             const restrictedPoolId = "read_only_pool";
             const restrictedConfig = createStandardPoolConfig({
@@ -529,7 +529,7 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
     await respecfully(sir, 'Revoke Lifecycle', async () => {
         let revokedKeystone: KeystoneIbGib_V1;
 
-        await ifWeMight(sir, 'successfully creates a revocation frame', async () => {
+        await ifWe(sir, 'successfully creates a revocation frame', async () => {
             revokedKeystone = await service.revoke({
                 latestKeystone: genesisKeystone,
                 masterSecret,
@@ -547,7 +547,7 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, data.revocationInfo!.proof.claim.verb).willEqual(KEYSTONE_VERB_REVOKE);
         });
 
-        await ifWeMight(sir, 'validates the revocation frame', async () => {
+        await ifWe(sir, 'validates the revocation frame', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: revokedKeystone!,
@@ -558,7 +558,7 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, errors.length).asTo('no validation errors').willEqual(0);
         });
 
-        await ifWeMight(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
+        await ifWe(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
             const data = revokedKeystone!.data!;
             const revokePool = data.challengePools.find(p => p.id === POOL_ID_REVOKE);
 
@@ -635,7 +635,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Happy Path', async () => {
-        await ifWeMight(sir, 'authorizes and adds a foreign pool', async () => {
+        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
             const bobPool = await createForeignPool("pool_bob", ["post"]);
 
             const updatedKeystone = await service.addPools({
@@ -674,7 +674,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Permissions & Logic', async () => {
-        await ifWeMight(sir, 'fails if no pool allows "manage" verb', async () => {
+        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
             // 1. Create a restricted keystone
             let id = "read_only";
             const restrictedConfig = createStandardPoolConfig({ id, salt: id });
@@ -707,7 +707,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
         });
 
-        await ifWeMight(sir, 'fails on ID collision', async () => {
+        await ifWe(sir, 'fails on ID collision', async () => {
             // Try to add "pool_bob" again (it was added in Happy Path)
             const duplicatePool = await createForeignPool("pool_bob");
 
@@ -796,7 +796,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Happy Path', async () => {
-        await ifWeMight(sir, 'authorizes and adds a foreign pool', async () => {
+        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
             const bobPool = await createForeignPool("pool_bob", ["post"]);
 
             const updatedKeystone = await service.addPools({
@@ -835,7 +835,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Permissions & Logic', async () => {
-        await ifWeMight(sir, 'fails if no pool allows "manage" verb', async () => {
+        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
             // 1. Create a restricted keystone (read-only)
             let id = "read_only";
             const restrictedConfig = createStandardPoolConfig({ id, salt: id });
@@ -868,7 +868,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
         });
 
-        await ifWeMight(sir, 'fails on ID collision', async () => {
+        await ifWe(sir, 'fails on ID collision', async () => {
             // Try to add "pool_bob" again (it was added in Happy Path)
             const duplicatePool = await createForeignPool("pool_bob");
 
@@ -930,7 +930,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
 
     await respecfully(sir, 'Proof Granularity & Math', async () => {
 
-        await ifWeMight(sir, 'generates exactly the expected number of solutions', async () => {
+        await ifWe(sir, 'generates exactly the expected number of solutions', async () => {
             signedKeystone = await service.sign({
                 latestKeystone: genesisKeystone,
                 masterSecret: aliceSecret,
@@ -947,7 +947,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             iReckon(sir, solutions.length).asTo('solution count').willEqual(4);
         });
 
-        await ifWeMight(sir, 'verifies the math manually (White-box Crypto Check)', async () => {
+        await ifWe(sir, 'verifies the math manually (White-box Crypto Check)', async () => {
             const proof = signedKeystone.data!.proofs[0];
             const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === salt)!;
 
@@ -976,7 +976,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             }
         });
 
-        await ifWeMight(sir, 'verifies FIFO logic (Deterministic Selection)', async () => {
+        await ifWe(sir, 'verifies FIFO logic (Deterministic Selection)', async () => {
             const proof = signedKeystone.data!.proofs[0];
             const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === salt)!;
 
@@ -998,7 +998,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
 
     await respecfully(sir, 'DTO & Serialization', async () => {
 
-        await ifWeMight(sir, 'survives a clone/JSON-cycle without corruption', async () => {
+        await ifWe(sir, 'survives a clone/JSON-cycle without corruption', async () => {
             // 1. Create a DTO (simulate network transmission/storage)
             // 'clone' does a JSON stringify/parse under the hood (usually) or structured clone.
             const dto = clone(signedKeystone);
@@ -1018,7 +1018,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             iReckon(sir, errors.length).asTo('DTO validation errors').willEqual(0);
         });
 
-        await ifWeMight(sir, 'ensures data contains no functions or circular refs', async () => {
+        await ifWe(sir, 'ensures data contains no functions or circular refs', async () => {
             // A crude but effective test: ensure JSON.stringify doesn't throw
             // and the result is equal to the object (if we parsed it back).
 

package/src/keystone/keystone-types.mts

@@ -1,6 +1,9 @@
+import { HashAlgorithm } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
 import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
 
 import { KEYSTONE_ATOM } from "./keystone-constants.mjs";
+import type { KeystoneVerb } from "./keystone-constants.mjs";
 
 // #region KeystoneChallengeType
 export const KEYSTONE_CHALLENGE_TYPE_HASH_REVEAL_V1 = 'hash-reveal-v1';
@@ -140,8 +143,8 @@ export interface KeystonePoolConfigBase {
 }
 
 export interface KeystonePoolConfig_HashV1 extends KeystonePoolConfigBase {
-    type: 'hash-reveal-v1';
-    algo: 'SHA-256' | 'SHA-512';
+    type: typeof KeystoneChallengeType.hash_reveal_v1;
+    algo: HashAlgorithm;
     rounds: number;
 }
 
@@ -157,7 +160,7 @@ export interface KeystoneChallengeBase {
 
 export interface KeystoneChallenge_HashV1 extends KeystoneChallengeBase {
     id: string;
-    type: 'hash-reveal-v1';
+    type: typeof KeystoneChallengeType.hash_reveal_v1;
     /**
      * The hash that must be matched by the solution.
      */
@@ -258,12 +261,29 @@ export interface KeystoneChallengePool {
 }
 
 /**
- * Semantic intent.
+ * Describes the specific privilege that the evolution of the keystone
+ * authorizes.
  */
 export interface KeystoneClaim {
-    target: string; // ibGib address
-    verb: string;   // ibGib address (primitive)
-    scope?: string; // ibGib address (primitive)
+    /**
+     * what action/ability does the claim make?
+     *
+     * @see {@link KeystoneVerb} and all of its members for just a list of some
+     * common verbs. But really, this can be any string.
+     */
+    verb: string;
+    /**
+     * What specific ibgib does this claim relate to?
+     *
+     * For example, if we are signing a keystone to witness some specific ibgib
+     * itself, similar to the most conventional use of digital signatures, then
+     * this will be the address of that ibgib.
+     */
+    target: IbGibAddr;
+    /**
+     * What limitations are narrowed down to beyond just target + verb?
+     */
+    scope?: string;
 }
 
 /**
@@ -336,7 +356,10 @@ export interface KeystoneRel8ns_V1 extends IbGibRel8ns_V1 {
     // Specific hard-links for composite keystones go here later.
 }
 
-export interface KeystoneIbGib_V1 extends IbGib_V1<KeystoneData_V1, KeystoneRel8ns_V1> { }
+export interface KeystoneIbGib_V1 extends IbGib_V1<KeystoneData_V1, KeystoneRel8ns_V1> {
+    data: KeystoneData_V1;
+    rel8ns: KeystoneRel8ns_V1;
+}
 
 export interface DeterministicResult {
     /**

package/src/sync/sync-conflict-adv-multitimelines.respec.mts

@@ -85,7 +85,7 @@ await respecfully(sir, `Multi-round/timeline permutations`, async () => {
     async function newTestPeer(): Promise<SyncPeerInnerspace_V1> {
         const peer = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
         await peer.initialized;
-        await peer.initializeSender({
+        await peer.initializeOpts({
             senderSpace: sourceSpace,
             receiverSpace: destSpace,
             receiverCoordinator: receiverCoordinator,

package/src/sync/sync-conflict-basic-divergence.respec.mts

@@ -221,7 +221,7 @@ await respecfully(sir, `Two different fields`, async () => {
 
             const peer = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
             await peer.initialized;
-            await peer.initializeSender({
+            await peer.initializeOpts({
                 senderSpace: sourceSpace,   // "Client"
                 receiverSpace: destSpace,   // "Server"
                 receiverCoordinator,

package/src/sync/sync-conflict-basic-multitimelines.respec.mts

@@ -207,7 +207,7 @@ await respecfully(sir, `Two different fields and rel8d`, async () => {
 
     const peer = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
     await peer.initialized;
-    await peer.initializeSender({
+    await peer.initializeOpts({
         senderSpace: sourceSpace,   // "Client"
         receiverSpace: destSpace,   // "Server"
         receiverCoordinator,