@ibgib/core-gib 0.1.47 → 0.1.48

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;
 }
 
 /**

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,

package/src/sync/sync-conflict-text-merge.respec.mts

@@ -87,7 +87,7 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, 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-constants.mts

@@ -1,4 +1,7 @@
+import { HashAlgorithm } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
 import { ROOT_ADDR } from "@ibgib/ts-gib/dist/V1/constants.mjs";
+import { KeystoneReplenishStrategy } from "../keystone/keystone-types.mjs";
+import { KEYSTONE_VERB_MANAGE, KEYSTONE_VERB_SIGN, POOL_ID_DEFAULT, POOL_ID_DELEGATE, POOL_ID_TRANSITION } from "../keystone/keystone-constants.mjs";
 
 export const SYNC_ATOM = "sync";
 
@@ -78,6 +81,18 @@ export function isValidSyncConflictStrategy(strategy: string): strategy is SyncC
 }
 // #endregion SyncConflictStrategy
 
+/**
+ * to be used by the sender
+ */
+export const SESSION_IDENTITY_KEYSTONE_PRIMARY_POOL_ID = POOL_ID_DEFAULT;
+/**
+ * single use pool
+ */
+export const SESSION_IDENTITY_KEYSTONE_TRANSITION_POOL_ID = POOL_ID_TRANSITION;
+/**
+ * to be used by the receiver, created via the single-use transition pool.
+ */
+export const SESSION_IDENTITY_KEYSTONE_DELEGATE_POOL_ID = POOL_ID_DELEGATE;
 /**
  * When synchronizing, the plan for identity integration is to create a session
  * keystone. This keystone will have a primary pool, driven by the sender's
@@ -86,4 +101,39 @@ export function isValidSyncConflictStrategy(strategy: string): strategy is SyncC
  * use this to then change the keystone to use a secret chosen by the
  * receiver's end.
  */
-export const DEFAULT_SESSION_IDENTITY_INITIAL_DELEGATE_SECRET = ROOT_ADDR;
+export const SESSION_IDENTITY_KEYSTONE_SECRET_TRANSITIONPOOL = ROOT_ADDR;
+
+/**
+ * has to be big enough to avoid our currently poor (atow 02/24/2026)
+ * implementation of the binding target.
+ */
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_SIZE = 100;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_ALGO = HashAlgorithm.sha_256;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_ROUNDS = 3;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_RANDOM = 2;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_SEQUENTIAL = 2;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_TARGET_BINDING = 4;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_REPLENISH_STRATEGY = KeystoneReplenishStrategy.topUp;
+/**
+ * verbs associated with primary/sender participant.
+ *
+ * todo: would be slightly cleaner to have the sender/primary genesis with two pools, one for signing and one being one-time manage use (to add the transition pool) just like the transition pool, but this is a finesse and not for V1. Still it is neat that this possibility/mechanism exists.
+ */
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_VERBS_PRIMARY = [KEYSTONE_VERB_MANAGE];
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_VERBS_DELEGATE = [KEYSTONE_VERB_SIGN];
+
+/**
+ * transition pool is purposefully weak with a known password.
+ */
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_SIZE_TRANSITIONPOOL = 1;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_ALGO_TRANSITIONPOOL = HashAlgorithm.sha_256;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_ROUNDS_TRANSITIONPOOL = 1;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_RANDOM_TRANSITIONPOOL = 0;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_SEQUENTIAL_TRANSITIONPOOL = 1;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_TARGET_BINDING_TRANSITIONPOOL = 0;
+/**
+ * This pool is to be used only once, by the receiver, in order for the receiver
+ * to create their own pool.
+ */
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_REPLENISH_STRATEGY_TRANSITIONPOOL = KeystoneReplenishStrategy.deleteAll;
+export const SESSION_IDENTITY_KEYSTONE_CONFIG_VERBS_TRANSITIONPOOL = [KEYSTONE_VERB_MANAGE];

package/src/sync/sync-innerspace-constants.respec.mts

@@ -72,7 +72,7 @@ await respecfully(sir, `Sync Constants (No TJP)`, 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-innerspace-deep-updates.respec.mts

@@ -103,7 +103,7 @@ await respecfully(sir, `Sync InnerSpaces (Deep Updates)`, 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-innerspace-dest-ahead-withid.respec.mts

@@ -29,6 +29,8 @@ import { ErrorIbGib_V1 } from '../common/error/error-types.mjs';
 import { SyncIbGib_V1 } from './sync-types.mjs';
 import { getFullSyncSagaHistory } from './sync-helpers.mjs';
 import { getIbGibsFromCache_fallbackToSpaces } from '../common/other/ibgib-helper.mjs';
+import { SyncSagaContextIbGib_V1 } from './sync-saga-context/sync-saga-context-types.mjs';
+import { isSyncSagaContextIbGib } from './sync-saga-context/sync-saga-context-helpers.mjs';
 
 const logalot = false;
 const lc = `[sync-innerspace-dest-ahead.respec]`;
@@ -38,6 +40,9 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
     let metaspace: Metaspace_Innerspace;
     let sourceSpace: InnerSpace_V1;
     let destSpace: InnerSpace_V1;
+    let secretSender = 'secret for sender';
+    let secretReceiver = 'secret for receiver';
+    let secretAdversary = 'secret for adversary';
 
     interface TestData {
         type: string;
@@ -119,7 +124,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
             return resGet.success && resGet.ibGibs && resGet.ibGibs.length === 1;
         }
 
-        await ifWe(sir, 'verify setup', async () => {
+        await ifWeMight(sir, 'verify setup', async () => {
             // Ensure V2 is ONLY in Dest (it is, per `space: destSpace`)
             // Ensure Source does NOT have V2
             iReckon(sir, await fnAddrExistsInSpace(addrV0, sourceSpace)).asTo('source has V0').isGonnaBeTrue();
@@ -137,7 +142,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, 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,
@@ -152,8 +157,10 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
             metaspace: metaspace,
             domainIbGibs: [v1], // Source tries to push V1
             useSessionIdentity: true,
+            identitySecret: secretSender,
         });
 
+        const syncSagaContextIbGibs: SyncSagaContextIbGib_V1[] = [];
         const sublc = `${lc}[updates$]`;
         /**
          * I have added this so you can see how to subscribe to an ibgib
@@ -163,6 +170,11 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
             next: async (ctxIbGib) => {
                 // console.log(`${sublc} next fired. ${JSON.stringify(ctxIbGib)}`);
                 console.log(`${sublc} next fired. (I: e68d8894bac8800f9f3430e8a38d6626)`);
+                // each context ibgib
+                if (!isSyncSagaContextIbGib(ctxIbGib)) {
+                    throw new Error(`(UNEXPECTED) ctxIbGib isn't a SyncSagaContextIbGib_V1? (E: ee116e6b6208e615dbcd3e715643e826)`);
+                }
+                syncSagaContextIbGibs.push(ctxIbGib);
             },
             error: async (e: ErrorIbGib_V1) => {
                 if (e.data) {
@@ -178,17 +190,10 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
         }));
         await done;
 
-        // TODO: Get saga IbGib to access session keystones
-        // Bill suggested either:
-        // 1. Subscribe to updates$ to inspect frames as sync progresses
-        // 2. Change done from Promise<void> to Promise<IbGibAddr>, return saga addr,
-        //    then use getIbGibsFromCache_fallbackToSpaces and getFullSyncSagaHistory
-        // For now, leaving implementation for next step.
-
         // 5. Verify Sync (v2 should be in both source and dest now)
         console.log(`${lc} Verifying Sync...`);
 
-        await ifWe(sir, `verify v2 now also in source`, async () => {
+        await ifWeMight(sir, `verify v2 now also in source`, async () => {
             // Verify Tip (V2)
 
             iReckon(sir, await fnAddrExistsInSpace(addrV0, sourceSpace)).asTo('source has V0').isGonnaBeTrue();
@@ -200,7 +205,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
 
         });
 
-        await ifWe(sir, `dependency graphs the same`, async () => {
+        await ifWeMight(sir, `dependency graphs the same`, async () => {
 
             const sourceDepGraph = await getDependencyGraph({
                 ibGibAddr: addrV2,
@@ -229,11 +234,23 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
         // For now, we'll retrieve from spaces after sync completes
         let sessionKeystoneAddr: IbGibAddr | undefined;
 
-        await ifWe(sir, 'IDENTITY: session keystone exists in sender space', async () => {
+        await ifWeMight(sir, 'IDENTITY: session keystone exists in sender space', async () => {
             // TODO: Get saga IbGib and access sessionKeystones rel8n
             // Once saga access is implemented (per Bill's guidance), retrieve keystone addr from:
             // const keystoneAddrs = sagaIbGib.rel8ns?.sessionKeystones;
             // Then verify keystone exists in space
+            debugger;
+
+            // #region leaving off here
+
+            // receiver is not putting the session keystone on the return
+            // context ibgib.  need to ensure that peer's do the most recent
+            // session keystone manually, so session keystone should be
+            // transferred alongside context ibgib (which is signed but
+            // intrinsically points to the **previous** frame of the keystone)
+
+            // #endregion leaving off here
+            syncSagaContextIbGibs.forEach(x => console.log(pretty(x)));
 
             // Placeholder - test passes because keystone creation works
             iReckon(sir, true)
@@ -241,7 +258,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
                 .isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'IDENTITY: session keystone exists in receiver space', async () => {
+        await ifWeMight(sir, 'IDENTITY: session keystone exists in receiver space', async () => {
             // Session keystone should be transferred to receiver's durable space
             iReckon(sir, sessionKeystoneAddr)
                 .asTo('session keystone address was captured')
@@ -255,7 +272,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
             }
         });
 
-        await ifWe(sir, 'IDENTITY: saga frames are signed', async () => {
+        await ifWeMight(sir, 'IDENTITY: saga frames are signed', async () => {
             // TODO: Get saga frames and check each has a proof
             // This will FAIL when we actually check - that's the point (TDD RED)
 
@@ -264,7 +281,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
                 .isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'IDENTITY: frame signatures are valid', async () => {
+        await ifWeMight(sir, 'IDENTITY: frame signatures are valid', async () => {
             // TODO: For each saga frame, validate proof against session keystone
             // const isValid = await validateProofWithKeystone({
             //     proof: frame.proof,
@@ -279,7 +296,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
                 .isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'IDENTITY: session keystone challenges are depleted', async () => {
+        await ifWeMight(sir, 'IDENTITY: session keystone challenges are depleted', async () => {
             // TODO: Session keystone should evolve after signing frames
             // This will FAIL because keystone evolution not implemented yet
 
@@ -288,7 +305,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
                 .isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'IDENTITY: frame timestamps are present and fresh', async () => {
+        await ifWeMight(sir, 'IDENTITY: frame timestamps are present and fresh', async () => {
             // TODO: Check each frame has timestamp in proof claim
             // const claim = JSON.parse(frame.proof.claim.scope);
             // iReckon(sir, claim.timestamp).asTo('has timestamp').isGonnaBeTruthy();
@@ -301,7 +318,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
                 .isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'IDENTITY: keystone has no hard links to domain ibgibs', async () => {
+        await ifWeMight(sir, 'IDENTITY: keystone has no hard links to domain ibgibs', async () => {
             if (sessionKeystoneAddr) {
                 const keystoneResult = await getFromSpace({
                     addr: sessionKeystoneAddr,
@@ -326,7 +343,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
             }
         });
 
-        await ifWe(sir, 'IDENTITY: saga frames have no hard links to domain ibgibs', async () => {
+        await ifWeMight(sir, 'IDENTITY: saga frames have no hard links to domain ibgibs', async () => {
             // Saga frames should NOT have hard links to domain ibgibs
             // This currently PASSES but will expose issues if hard links exist
 

package/src/sync/sync-innerspace-dest-ahead.respec.mts

@@ -134,7 +134,7 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, 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-innerspace-multiple-timelines.respec.mts

@@ -107,7 +107,7 @@ await respecfully(sir, `Sync InnerSpaces (Multiple Timelines)`, 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-innerspace-partial-update.respec.mts

@@ -115,7 +115,7 @@ await respecfully(sir, `Sync InnerSpaces (Partial Update)`, 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-innerspace.respec.mts

@@ -107,7 +107,7 @@ await respecfully(sir, `Sync InnerSpaces`, async () => {
         // Peer (The "Network")
         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,