@ibgib/core-gib 0.1.42 → 0.1.44

package/src/sync/README.md

@@ -39,15 +39,132 @@ Init -> Ack -> Delta(s) -> Conflict/Commit via "ping pong" exchange.
     * For local-only syncs, the `SyncPeer_V1` implementation is responsible for moving verified `ibGibs` from the temporary saga space to the durable/persistent domain space.
 *   From each endpoint's POV, the cleanup should remove the temp spaces used, in addition to any other required transaction cleanup (like closing any connections).
 
-### Ephemeral Identity (`useSessionIdentity`)
+### Session Identity (`useSessionIdentity`)
+
 The sync protocol can optionally generate an ephemeral Keystone Identity for the duration of the saga.
-*   **Purpose**: Allows secure, signed exchanges even if the Node doesn't have a long-lived identity, or wishes to isolate the sync session.
-*   **Mechanism**: If `useSessionIdentity: true` (default) is passed to `sync()`, a new Keystone frame is generated and linked to the Saga.
-*   **Pending Work**: Full verification of these ephemeral signatures is currently pending implementation.
+
+**Purpose**: To allow secure, signed exchanges even if the Node doesn't have a long-lived identity, or to isolate the sync session security from master identity.
+
+**Current Status**:
+*   ✅ Session keystone creation implemented ([getSessionIdentity()](file:./sync-saga-coordinator.mts#L328-L362))
+*   ✅ Keystone passed via Init message ([initData.identity](file:./sync-saga-message/sync-saga-message-types.mts#L75))
+*   ⚠️ **Signature generation/verification: NOT yet implemented**
+*   ⚠️ **Per-frame proof creation: NOT yet implemented**
+
+**Usage**:
+```typescript
+const { done } = await coordinator.sync({
+  peer,
+  domainIbGibs: [timeline],
+  localSpace,
+  metaspace,
+  useSessionIdentity: true, // Default, but currently non-functional
+});
+```
+
+> [!CAUTION]
+> **🚧 Session identity is NOT working yet.** Tests explicitly set `useSessionIdentity: false` to avoid failures. See [sync-innerspace-dest-ahead-withid.respec.mts](file:./sync-innerspace-dest-ahead-withid.respec.mts) for the failing test case.
+
+**Authentication/Authorization Hooks**:
+
+Validation occurs in [SyncPeer_V1.witness()](file:./sync-peer/sync-peer-v1.mts#L129-L219):
+1. `validateContextAndSagaFrame()` - Intrinsic validation
+2. `authenticateContext()` - Verify identity (stub)
+3. `authorizeContext()` - Check permissions (stub)
+
+### Conflict Resolution via Grafting
+
+> [!IMPORTANT]
+> **🔀 When timelines diverge**, the sync protocol uses **grafting** to merge branches.
+
+**Mechanism**:
+1. **Detect divergence** in Ack stage (tips differ, neither recognizes other's tip)
+2. **Exchange full timeline history** via `SyncSagaConflictInfo.receiverKnowledgeTimelineAddrs`
+3. **Find Latest Common Ancestor (LCA)**
+4. **Replay DNA transforms** from both branches
+5. **Create graft timeline** with merged result
+6. **Track via** `GraftInfoIbGib_V1` ([graft-info-types.mts](file:./graft-info/graft-info-types.mts))
+
+**Conflict Info Tracking**:
+*   `graftInfoAddr`: Points to graft metadata
+*   `createdDnaAddrs`: DNA ibgibs created during merge
+*   `replayedDnaAddrs`: Original DNAs replayed
+*   `createdDomainAddrs`: Final timeline frames (in order)
+
+See [graft-info-helpers.mts](file:./graft-info/graft-info-helpers.mts) for implementation.
+
+### Transaction Model (Temp Spaces)
+
+> [!NOTE]
+> **💾 Sync uses a two-phase commit pattern** with temporary spaces for atomic operations.
+
+**Phases**:
+1. **Accumulation**: Domain ibgibs received during sync go to `tempSpace`
+2. **Commit**: On successful saga completion, verified ibgibs move to durable `localSpace`
+
+**Rollback**: If saga fails, temp space cleanup discards unverified data.
+
+**Lifecycle**:
+*   **Created**: `tempSpace = await metaspace.createNewLocalSpace()` at saga start
+*   **Destroyed**: Cleanup function runs in `sync()` finally block
+
+**Why**: Ensures atomic sync - either all data validates and commits, or none does.
+
+
+## 🔒 Security Considerations
+
+> [!WARNING]
+> Session identity is **currently non-functional**. The mitigations below describe the intended security model.
+
+### Attack Vectors & Mitigations
+
+| Attack Vector | Description | Mitigation |
+|---------------|-------------|------------|
+| **MITM Replay** | Attacker replays captured saga frames | • Frame signatures include timestamp<br>• Freshness checks reject old frames<br>• Challenge depletion prevents reuse<br>• sagaId deduplication |
+| **Session Fixation** | Attacker pre-generates session keystone | • Session secret derived via KDF (strategy in keystone metadata)<br>• `sessionSecret = KDF(masterSecret, sagaId, strategy)` |
+| **Identity Spoofing** | Impersonation via fake session keystone | • Session keystone includes `derivedFrom` master address<br>• Receiver validates master keystone is known/trusted |
+| **Challenge Grinding** | Brute-force challenge solutions for target binding | • Hash pre-imaging computationally infeasible<br>• Stochastic selection adds randomness |
+| **DoS (Pool Exhaustion)** | Excessive syncs deplete challenge pools | • Top-up replenishment refills challenges<br>• Rate limiting per identity<br>• Pool separation for critical ops |
+| **Saga Hijacking** | Mid-flight frame injection | • All frames signed with session keystone<br>• `past` rel8n creates tamper-evident chain |
+
+### Cryptographic Primitives
+
+*   **Hash Function**: SHA-256 (content addressing, challenge generation)
+*   **Proof System**: Hash-reveal protocol (`hash-reveal-v1`)
+*   **Binding**: Target address → hex bucket → challenge selection
+*   **Entropy**: Stochastic challenge selection (anti-grinding)
+
+### Trust Model
+
+**Session Keystones**:
+- Ephemeral identity per sync saga
+- Derived from master keystone + `sagaId`
+- Validates via proof-of-work (solving challenges)
+- Post-hoc audit trail: master can prove session authorship
+
+**Propagation**:
+- Sync does NOT rely on global PKI or certificate authorities
+- Trust propagates through sync sessions (Alice syncs with Bob → Bob witnesses Alice's keystone)
+- Revocation propagates same way (Alice revokes → syncs revocation to Bob → Bob sees revoked timeline)
+
+**Threat Boundaries**:
+- ✅ Protects against: MITM replay, impersonation, frame tampering
+- ⚠️ Does NOT protect against: Compromised endpoint (live memory access during active session)
+- ⚠️ Master secrets: Raw secrets should NOT stored; keystones master secrets to keystones should be derived secrets via key stretching passwords. raw secret files of course can drive these passwords and must be protected
+- ⚠️ Transport security: Use TLS for network layer encryption (ibgib protocol provides authentication/integrity, not confidentiality)
+
+### Best Practices
+
+1. **Master Secret Protection**: Store master secrets in secure enclaves/keychains
+2. **Session Lifetime**: Limit saga duration, revoke sessions post-completion
+3. **Rate Limiting**: Implement per-identity sync rate limits
+4. **Freshness**: Reject frames older than 60 seconds
+5. **Audit Logs**: Persist saga timelines for post-hoc validation (saga timelines are ibgibs, so integrity is built-in via content addressing)
+6. **TLS**: Always use TLS for network transport (defense-in-depth)
 
 ## 📚 Documentation
 *   **[Architecture](./docs/architecture.md)**: Detailed design of the Saga Protocol, State Machine, and Smart Diff logic.
-*   **[Verification](./docs/verification.md)**: Test matrix, scenarios, and verification results.
+*   **[Testing & Verification](./docs/testing.md)**: Test strategy, verification matrix, and comprehensive testing guidelines.
 
 ## Features
 *   **Symmetric Design**: No distinct "Client" or "Server" logic.

package/src/sync/docs/architecture.md

@@ -42,7 +42,7 @@ The `SyncSagaCoordinator` drives a Finite State Machine (FSM) via the `handleSag
 
 4.  **Convergence (`handleDeltaFrame`)**:
     *   Bob receives `Delta`.
-    *   **Verifies**: Checks hashes (`ib` vs `gib`) and signatures.
+    *   **Verifies**: Checks content-address hashes (`ib` vs `gib`). ⚠️ Keystone signature verification pending.
     *   **Merges**: Puts data into his local space.
     *   Bob sends `Commit` frame.
 
@@ -65,5 +65,5 @@ The protocol supports two types of data:
 *   **Stones (Constants)**: Immutable data without a history (e.g., Code lists, Configs). Syncing involves simple existence checks.
 
 ## 4. Security & Identity
-*   **Session Keystone**: Each Saga typically generates an ephemeral identity to sign frames, linked to a master identity.
+*   **Session Keystone**: Each Saga can optionally generate an ephemeral identity to sign frames, linked to a master identity. ⚠️ **Currently non-functional** - see [README Session Identity section](file:../README.md#session-identity-usesessionidentity) for status.
 *   **Trust Chain**: Each frame points to the previous one (`past` rel8n), creating a hash-linked chain of custody.

package/src/sync/{SYNC_TESTING.md → docs/testing.md}

@@ -1,38 +1,116 @@
-# Sync Testing Guidelines
+# Sync Protocol Testing & Verification
 
-💣💥 USE THESE GUIDELINES TO MITIGATE COMPLEXITY EXPLOSION 💣💥
+This document outlines the testing strategy, verification results, and comprehensive guidelines for testing the Symmetric Sync Protocol.
 
-Sync needs thorough testing and complexity increases exponentially. Ridiculously
-exponentially. I mean you won't believe just how vastly, hugely, mind-bogglingly
-fast...
+💣💥 **USE THESE GUIDELINES TO MITIGATE COMPLEXITY EXPLOSION** 💣💥
 
-## Core Concepts
+Sync needs thorough testing and complexity increases exponentially. Ridiculously exponentially. I mean you won't believe just how vastly, hugely, mind-bogglingly fast...
 
-### Rounds
+---
+
+## Testing Strategy
+
+We use `respec-gib` (a BDD-style framework) with **In-Memory Simulation (`InnerSpace`)** to verify logic. This allows us to test complex graph scenarios without network or disk I/O overhead.
+
+### Key Test Files
+
+To see the most up-to-date test files for sync, search inside `libs/core-gib/src/sync` for `*.respec.mts` files.
+
+**Basic Scenarios**:
+*   `sync-innerspace.respec.mts`: Basic Push/Pull scenarios
+*   `sync-innerspace-dest-ahead.respec.mts`: Receiver has newer data scenarios
+*   `sync-innerspace-multiple-timelines.respec.mts`: Multiple independent timelines in one saga
+*   `sync-innerspace-partial-update.respec.mts`: Smart diff verification (delta-only transfers)
+*   `sync-innerspace-deep-updates.respec.mts`: Timelines with extensive history (past link traversal)
+*   `sync-innerspace-constants.respec.mts`: Synchronization of stones (constants/non-TJPs)
+
+**Conflict Resolution**:
+*   `sync-conflict-basic-divergence.respec.mts`: Single timeline divergence and merge
+*   `sync-conflict-basic-multitimelines.respec.mts`: Multiple timelines with conflicts
+*   `sync-conflict-adv-multitimelines.respec.mts`: Advanced multi-timeline, multi-round sync
+*   `sync-conflict-text-merge.respec.mts`: LCS-based text merging for `data.text` fields
+
+**Identity & Security**:
+*   `sync-innerspace-dest-ahead-withid.respec.mts`: Session identity test (🚧 **currently failing**)
+
+---
+
+## Verification Matrix
+
+### 1. Basic Scenarios
+| Feature | Description | Status | Test File |
+| :--- | :--- | :--- | :--- |
+| **Push** | Source syncs a new timeline to an empty Dest. | ✅ Verified | `sync-innerspace.respec.mts` |
+| **Pull** | Dest requests data from Source (Reverse Sync). | ⏳ Pending | `sync-innerspace.respec.mts` |
+| **Dest Ahead** | Dest has newer data; Source receives update. | ✅ Verified | `sync-innerspace-dest-ahead.respec.mts` |
+
+### 2. Complex Graph Scenarios
+| Feature | Description | Status | Test File |
+| :--- | :--- | :--- | :--- |
+| **Multi-Timeline** | Syncing multiple separate timelines. | ✅ Verified | `sync-innerspace-multiple-timelines.respec.mts` |
+| **Deep Updates** | Syncing deep dependency chains (Ancestors). | ✅ Verified | `sync-innerspace-deep-updates.respec.mts` |
+| **Smart Diff** | Sender skips data Receiver already has. | ✅ Verified | `sync-innerspace-partial-update.respec.mts` |
+| **Constants** | Syncing immutable stones (no TJP). | ✅ Verified | `sync-innerspace-constants.respec.mts` |
+
+### 3. Conflict Resolution & Edge Cases
+| Feature | Description | Status | Test File |
+| :--- | :--- | :--- | :--- |
+| **Hash Validation** | Verifying integrity checks (ib/gib). | ✅ Verified | Built-in to all tests |
+| **Basic Conflicts** | Divergent branches (single timeline). | ✅ Verified | `sync-conflict-basic-divergence.respec.mts` |
+| **Multi-Timeline Conflicts** | Multiple timelines diverging. | ✅ Verified | `sync-conflict-basic-multitimelines.respec.mts` |
+| **Advanced Conflicts** | Complex multi-round scenarios. | ✅ Verified | `sync-conflict-adv-multitimelines.respec.mts` |
+| **Text Merge Conflicts** | LCS-based text merging. | ✅ Verified | `sync-conflict-text-merge.respec.mts` |
+
+### 4. Security & Identity
+| Feature | Description | Status | Test File |
+| :--- | :--- | :--- | :--- |
+| **Session Keystones** | Ephemeral identity for sync sessions. | 🚧 **Non-functional** | `sync-innerspace-dest-ahead-withid.respec.mts` |
+
+---
+
+## Recent Verifications
+
+### Sync Constants (2026-01-08)
+*   **Goal**: Ensure constants (ibGibs without `tjp` or `past`) are synced.
+*   **Result**: ✅ Passed.
+*   **Fixes**: Updated `handleInitFrame` to request missing stones; updated `handleAckFrame` to include "tip" stones in payload even without dependencies.
+
+### Text Merge Conflicts (2026-01-14)
+*   **Goal**: Verify LCS-based text merging for divergent `data.text` fields.
+*   **Result**: ✅ Passed.
+*   **Implementation**: Uses Longest Common Subsequence algorithm for three-way merge.
+
+---
+
+## Testing Guidelines
+
+### Core Concepts
+
+#### Rounds
 
 Tests are organized into **rounds**. Each round represents a complete cycle of:
 1. **State Setup**: Establish expected initial conditions
 2. **Actions**: Perform mutations, relations, and sync operations
 3. **Verification**: Assert final state expectations
 
-The **first round** is establishes common history between source and dest, and
-subsequent rounds perform one or more op(s) and sync(s).
+The **first round** establishes common history between source and dest, and subsequent rounds perform one or more op(s) and sync(s).
 
-### Broad Test Scenarios
+#### Broad Test Scenarios
 
 Here are the broad category of ops that can occur to timelines WRT syncing:
 * **Fast-Forward (Source Ahead)**: Source has newer versions that dest lacks
 * **Fast-Forward (Dest Ahead)**: Dest has newer versions that source lacks
 * **Conflict**: Both source and dest have divergent edits from a common ancestor
 * **No Change**: Timeline exists on both sides with no edits
-* **Stones**: Stones are treated slightly differently in the sync engine right
-  now, so these must also be tested in various permutations.
+* **Stones**: Stones are treated slightly differently in the sync engine right now, so these must also be tested in various permutations.
+
+---
 
 ## Variable Naming Convention
 
 Variable names are a COMBINATION of BOTH snake_case AND camelCase:
 
-Format: `round_timeline_version_location_commentsHereInCamelCase_possiblyOtherComments`
+**Format**: `round_timeline_version_location_commentsHereInCamelCase_possiblyOtherComments`
 
 ### Components
 
@@ -54,6 +132,8 @@ r1_delta_v1_source_createdInR1_rel8edFromAlpha  // Round 1, delta v1 with multip
 r2_alpha_v4_dest_postConflict               // Round 2, alpha v4 on dest, after conflict resolution
 ```
 
+---
+
 ## Test Structure
 
 ### File Organization
@@ -144,8 +224,7 @@ Pattern examples:
 
 * **`respecfully`**: Outer verification block per round with text "r{N} verify pre/post"
 * **`ifWeMight`**: Per-timeline verification within a round
-  * NOTE: Graphs should be used for verification of sync, not individual addrs/ibgibs
-    in most (all?) cases
+  * NOTE: Graphs should be used for verification of sync, not individual addrs/ibgibs in most (all?) cases
 * **`iReckon`**: Individual assertions
 
 Example:
@@ -163,15 +242,15 @@ await respecfully(sir, `r1 verify results`, async () => {
 });
 ```
 
+---
+
 ## Multiple Syncs Per Round
 
 A single round can have **multiple sync calls**. This is useful when:
 * Creating multiple timeline pairs (some on source, some on dest)
 * Testing specific sync scenarios in isolation
 
-Key principle: Verify **final state** at end of round, not intermediate states
-between syncs. We don't want to get bogged down trying to test every detail
-after every sync. The broad coverage should handle this.
+Key principle: Verify **final state** at end of round, not intermediate states between syncs. We don't want to get bogged down trying to test every detail after every sync. The broad coverage should handle this.
 
 ```typescript
 // Round 1: Establish common history
@@ -187,6 +266,8 @@ await respecfully(sir, `r1 verify all timelines synced`, async () => {
 });
 ```
 
+---
+
 ## Domain-Level Focus
 
 Advanced tests focus on **domain-level correctness**, not protocol mechanics:
@@ -195,6 +276,8 @@ Advanced tests focus on **domain-level correctness**, not protocol mechanics:
 ❌ **Don't use**: `delay()` calls to control base/orphan selection
 ✅ **Do focus on**: Data field correctness, relation preservation, dependency completeness
 
+---
+
 ## Complexity Management
 
 ### Principles
@@ -207,14 +290,9 @@ Advanced tests focus on **domain-level correctness**, not protocol mechanics:
 
 ### Test Transformer
 
-Tests are making relatively arbitrary fork/mut8/rel8 calls. To help reduce
-implementation detail noise, the `TestTransformer` helper class was created.
-
-These methods return a `TestStepInfo` which itself has references to the `ibGib`
-and `addr`, as well as other metadata. So the variable
-`r2_alpha_v2_source_arbitraryMut8` does NOT reference an ibgib, rather, it
-references one of these test step info objects.
+Tests are making relatively arbitrary fork/mut8/rel8 calls. To help reduce implementation detail noise, the `TestTransformer` helper class was created.
 
+These methods return a `TestStepInfo` which itself has references to the `ibGib` and `addr`, as well as other metadata. So the variable `r2_alpha_v2_source_arbitraryMut8` does NOT reference an ibgib, rather, it references one of these test step info objects.
 
 ```typescript
 const r2_beta_v0_source = await testTransformer.create({
@@ -233,6 +311,8 @@ const r2_alpha_v2_source_arbitraryMut8 = await testTransformer.mut8({
 
 See `test-helpers.mts` and `test-types.mts` for implementations.
 
+---
+
 ## Scenarios to Test
 
 ### Basic Scenarios
@@ -248,9 +328,14 @@ See `test-helpers.mts` and `test-types.mts` for implementations.
 * **Reverse dependencies**: Timeline created on dest, source adds rel8n to it
 * **Removal conflicts**: Source removes rel8n while dest mut8s the rel8'd ibgib
 * **Chain edits**: Mutation → rel8 → mutation again on same timeline in one round
-* **Text edits**: Edit ibGib.data.text. If this is found to be different in
-  divergent cases, then a special handler will try to merge the texts using
-  basic text merging algorithm.
+* **Text edits**: Edit `ibGib.data.text`. If divergent, uses LCS-based merge. See `sync-conflict-text-merge.respec.mts`.
+
+### Security Scenarios
+* **Session identity creation**: Verify ephemeral keystone generation (🚧 pending implementation)
+* **Signature verification**: (🚧 pending implementation)
+* **Authorization checks**: Verify identity-based permissions (🚧 pending implementation)
+
+---
 
 ## Summary
 

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

@@ -148,7 +148,7 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
             });
             const r1_alpha_source_tipAddr = r1_alpha_sourceKV[alpha_tjpAddr];
             if (!r1_alpha_source_tipAddr) {
-                ifWeMight(sir, 'r1_alpha_source_tipAddr is falsy?', async () => {
+                ifWe(sir, 'r1_alpha_source_tipAddr is falsy?', async () => {
                     iReckon(sir, true).asTo('fail').isGonnaBeFalse();
                 });
                 return; /* <<<< returns early */
@@ -161,17 +161,17 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
             });
             const r1_alpha_dest_tipAddr = r1_alpha_destKV[alpha_tjpAddr];
             if (!r1_alpha_dest_tipAddr) {
-                ifWeMight(sir, 'r1_alpha_dest_tipAddr is falsy?', async () => {
+                ifWe(sir, 'r1_alpha_dest_tipAddr is falsy?', async () => {
                     iReckon(sir, true).asTo('fail').isGonnaBeFalse();
                 });
                 return; /* <<<< returns early */
             }
 
-            await ifWeMight(sir, 'r1 tip addrs match', async () => {
+            await ifWe(sir, 'r1 tip addrs match', async () => {
                 iReckon(sir, r1_alpha_source_tipAddr).asTo('R1 source/dest have same tip').isGonnaBe(r1_alpha_dest_tipAddr);
             });
 
-            await ifWeMight(sir, 'r1 text synced correctly', async () => {
+            await ifWe(sir, 'r1 text synced correctly', async () => {
                 if (!r1_alpha_dest_tipAddr) {
                     throw new Error(`r1_dest_tipAddr is null/undefined (E: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d)`);
                 }
@@ -181,7 +181,7 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
                 iReckon(sir, destTipIbGib.data!.text).asTo('Dest has initial text').isGonnaBe(INITIAL_TEXT);
             });
 
-            await ifWeMight(sir, 'r1 dep graphs synced', async () => {
+            await ifWe(sir, 'r1 dep graphs synced', async () => {
                 const [r1_alpha_source_tip] = await getIbGibsFromCache_fallbackToSpaces({
                     addrs: [r1_alpha_source_tipAddr],
                     space: sourceSpace,
@@ -260,7 +260,7 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
     // #endregion r2 dest edits
 
     await respecfully(sir, `r2 verify pre`, async () => {
-        await ifWeMight(sir, 'texts as expected', async () => {
+        await ifWe(sir, 'texts as expected', async () => {
             // before the sync, each side only has their edit. after the sync,
             // both sides should have both prepended and appended text
             iReckon(sir, r2_alpha_v1_source_appendedText.ibGib.data?.text.includes(INITIAL_TEXT)).asTo('alpha source has initial text').isGonnaBeTrue();
@@ -296,14 +296,14 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
         const kv_dest = await senderCoordinator.getKnowledgeMap({ space: destSpace, metaspace, domainIbGibs: [r1_alpha_v0_source.ibGib] });
         const r2_alpha_source_tipAddr = kv_source[alpha_tjpAddr];
         if (!r2_alpha_source_tipAddr) {
-            await ifWeMight(sir, 'r2_alpha_source_tipAddr falsy?', async () => {
+            await ifWe(sir, 'r2_alpha_source_tipAddr falsy?', async () => {
                 iReckon(sir, true).asTo('fails').isGonnaBe(false);
             });
             return; /* <<<< returns early */
         }
         const r2_alpha_dest_tipAddr = kv_dest[alpha_tjpAddr];
         if (!r2_alpha_dest_tipAddr) {
-            await ifWeMight(sir, 'r2_alpha_dest_tipAddr falsy?', async () => {
+            await ifWe(sir, 'r2_alpha_dest_tipAddr falsy?', async () => {
                 iReckon(sir, true).asTo('fails').isGonnaBe(false);
             });
             return; /* <<<< returns early */
@@ -317,11 +317,11 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
             space: sourceSpace,
         });
 
-        await ifWeMight(sir, 'r2 tip addrs match', async () => {
+        await ifWe(sir, 'r2 tip addrs match', async () => {
             iReckon(sir, r2_alpha_source_tipAddr).asTo('alpha').isGonnaBe(r2_alpha_dest_tipAddr);
         });
 
-        await ifWeMight(sir, 'r2 text merged correctly', async () => {
+        await ifWe(sir, 'r2 text merged correctly', async () => {
             // before the sync, each side only has their edit. after the sync,
             // both sides should have both prepended and appended text
             iReckon(sir, r2_alpha_v1_source_appendedText.ibGib.data?.text.includes(INITIAL_TEXT)).asTo('alpha source has initial text').isGonnaBeTrue();
@@ -340,7 +340,7 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
             iReckon(sir, text).asTo('R2 has both prepend and append').isGonnaBe(DEST_PREPEND + INITIAL_TEXT + SOURCE_APPEND);
         });
 
-        await ifWeMight(sir, 'r2 dep graphs synced', async () => {
+        await ifWe(sir, 'r2 dep graphs synced', async () => {
             // alpha's full dep graph should exist on dest
             const depGraph_alpha_source = await getDependencyGraph({
                 ibGib: r2_alpha_source_tip,
@@ -414,7 +414,7 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
     // // #endregion r3 dest edits
 
     // await respecfully(sir, `r3 verify pre`, async () => {
-    //     await ifWeMight(sir, 'dest has alpha after R2 graft', async () => {
+    //     await ifWe(sir, 'dest has alpha after R2 graft', async () => {
     //         const kv = await receiverCoordinator.getKnowledgeMap({ space: destSpace, metaspace, domainIbGibs: [r3_v0_graft_fromDest] });
     //         iReckon(sir, !!kv[alpha_tjpAddr]).asTo('dest has tip').isGonnaBeTrue();
     //     });
@@ -445,11 +445,11 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
     //     const r3_tip_s = kv_s[alpha_tjpAddr];
     //     const r3_tip_d = kv_d[alpha_tjpAddr];
 
-    //     await ifWeMight(sir, 'r3 tip addrs match', async () => {
+    //     await ifWe(sir, 'r3 tip addrs match', async () => {
     //         iReckon(sir, r3_tip_s).asTo('R3 tips match').isGonnaBe(r3_tip_d);
     //     });
 
-    //     await ifWeMight(sir, 'r3 both paragraph edits merged', async () => {
+    //     await ifWe(sir, 'r3 both paragraph edits merged', async () => {
     //         const res = await getFromSpace({ space: sourceSpace, addr: r3_tip_s! });
     //         const tip = res.ibGibs![0] as IbGib_V1<TestData>;
     //         const mergedText = tip.data!.text!;
@@ -468,7 +468,7 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
     //             .isGonnaBeTrue();
     //     });
 
-    //     await ifWeMight(sir, 'r3 dep graphs synced', async () => {
+    //     await ifWe(sir, 'r3 dep graphs synced', async () => {
     //         const [d] = await getIbGibsFromCache_fallbackToSpaces({ addrs: [r3_tip_s!], space: destSpace });
     //         iReckon(sir, d).asTo('exists dest').isGonnaBeTruthy();
     //     });
@@ -502,7 +502,7 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
     // // #endregion r4 dest edits
 
     // await respecfully(sir, `r4 verify pre`, async () => {
-    //     await ifWeMight(sir, 'dest has alpha after R3 graft', async () => {
+    //     await ifWe(sir, 'dest has alpha after R3 graft', async () => {
     //         // TODO: Verify pre-sync state
     //     });
     // });
@@ -512,16 +512,16 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
     // // TODO: Add sync operation
 
     // await respecfully(sir, `r4 verify post`, async () => {
-    //     await ifWeMight(sir, 'r4 tip addrs match', async () => {
+    //     await ifWe(sir, 'r4 tip addrs match', async () => {
     //         // TODO: Verify tips match
     //     });
 
-    //     await ifWeMight(sir, 'r4 LCS merged both word changes', async () => {
+    //     await ifWe(sir, 'r4 LCS merged both word changes', async () => {
     //         // TODO: Verify text has both source and dest word changes
     //         // TODO: Verify LCS algorithm preserved both edits correctly
     //     });
 
-    //     await ifWeMight(sir, 'r4 dep graphs synced', async () => {
+    //     await ifWe(sir, 'r4 dep graphs synced', async () => {
     //         // TODO: Verify dep graphs
     //     });
     // });
@@ -556,7 +556,7 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
     // // #endregion r5 dest edits
 
     // await respecfully(sir, `r5 verify pre`, async () => {
-    //     await ifWeMight(sir, 'dest has alpha after R4 graft', async () => {
+    //     await ifWe(sir, 'dest has alpha after R4 graft', async () => {
     //         // TODO: Verify pre-sync state
     //     });
     // });
@@ -566,24 +566,24 @@ await respecfully(sir, `Text merge (LCS) conflict resolution`, async () => {
     // // TODO: Add sync operation
 
     // await respecfully(sir, `r5 verify post`, async () => {
-    //     await ifWeMight(sir, 'r5 tip addrs match', async () => {
+    //     await ifWe(sir, 'r5 tip addrs match', async () => {
     //         // TODO: Verify tips match
     //     });
 
-    //     await ifWeMight(sir, 'r5 text field merged', async () => {
+    //     await ifWe(sir, 'r5 text field merged', async () => {
     //         // TODO: Verify text field has both source and dest changes
     //     });
 
-    //     await ifWeMight(sir, 'r5 description field merged', async () => {
+    //     await ifWe(sir, 'r5 description field merged', async () => {
     //         // TODO: Verify description field has both source and dest changes
     //     });
 
-    //     await ifWeMight(sir, 'r5 both fields independently LCS-merged', async () => {
+    //     await ifWe(sir, 'r5 both fields independently LCS-merged', async () => {
     //         // TODO: Verify each field was merged independently
     //         // TODO: Ensure one field's merge didn't affect the other
     //     });
 
-    //     await ifWeMight(sir, 'r5 dep graphs synced', async () => {
+    //     await ifWe(sir, 'r5 dep graphs synced', async () => {
     //         // TODO: Verify dep graphs
     //     });
     // });

package/src/sync/sync-constants.mts

@@ -1,3 +1,5 @@
+import { ROOT_ADDR } from "@ibgib/ts-gib/dist/V1/constants.mjs";
+
 export const SYNC_ATOM = "sync";
 
 export const SYNC_MSG_REL8N_NAME = "syncmsg";
@@ -75,3 +77,13 @@ export function isValidSyncConflictStrategy(strategy: string): strategy is SyncC
     return SYNC_CONFLICT_STRATEGY_VALID_VALUES.includes(strategy as SyncConflictStrategy);
 }
 // #endregion SyncConflictStrategy
+
+/**
+ * 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
+ * secret, and a secondary delegated pool for use by the receiver. Initially,
+ * this will have a known, weak "secret" and it is the job of the receiver to
+ * 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;