@ibgib/core-gib 0.1.41 → 0.1.43

package/src/keystone/README.md

@@ -16,5 +16,123 @@ Validation in this system is **Auditability**: to verify an identity (e.g., "Is
 3.  **Hash-based**: Uses hash pre-imaging for quantum resistance (`hash-reveal-v1`).
 4.  **Merkle Graphs**: Efficient communication by only transmitting missing graph nodes.
 
+## Challenge Pools
+
+Keystones organize challenges into **pools** with specific purposes:
+
+*   **Default Pool**: General-purpose signing operations
+*   **Revoke Pool**: Permanent identity termination (one-time use, `verb: revoke`)
+*   **Manage Pool**: Structural changes like adding pools (`verb: manage`)
+*   **Foreign Pools**: Delegation to external identities (SSO-like workflows)
+
+Each pool configuration specifies:
+*   **`poolId`**: Unique identifier within the keystone
+*   **`verb`**: Auto-routes operations (e.g., `revoke`, `manage`, `login`)
+*   **`replenishStrategy`**: `'top-up'` (reusable) or `'scorched-earth'` (burn after use)
+*   **`challengeCount`**: Number of hash challenges in the pool
+
+## Basic Usage
+
+### Genesis (Create Identity)
+
+```typescript
+const keystone = await keystoneService.genesis({
+  masterSecret: "user-password",
+  configs: [
+    { poolId: 'default', challengeCount: 100, replenishStrategy: 'top-up' },
+    { poolId: 'revoke', verb: 'revoke', challengeCount: 10, replenishStrategy: 'scorched-earth' }
+  ],
+  metaspace,
+  space
+});
+```
+
+### Sign a Claim
+
+```typescript
+const signedKeystone = await keystoneService.sign({
+  latestKeystone: keystone,
+  claim: { action: 'login', timestamp: Date.now() },
+  masterSecret: "user-password",
+  poolId: 'default', // or use verb-based auto-routing
+  metaspace,
+  space
+});
+```
+
+### Revoke Identity
+
+```typescript
+await keystoneService.revoke({
+  latestKeystone: keystone,
+  reason: "Device compromised",
+  masterSecret: "user-password",
+  metaspace,
+  space
+});
+```
+
+## Delegation via Foreign Pools
+
+> [!IMPORTANT]
+> **🔑 Foreign pools enable delegation** - Alice can grant Bob signing authority for specific operations.
+
+Alice can delegate signing authority to Bob by adding his challenge pool:
+
+```typescript
+const aliceWithBobPool = await keystoneService.addPools({
+  latestKeystone: aliceKeystone,
+  newPoolConfigs: [
+    {
+      poolId: 'bob-sso',
+      verb: 'login',
+      foreignServerUrl: 'https://bob-server.com',
+      challengeCount: 50
+    }
+  ],
+  masterSecret: aliceSecret,
+  metaspace,
+  space
+});
+```
+
+Now Bob can sign login claims on Alice's behalf, but only for operations using the `login` verb.
+
+**Trust Model**:
+- Alice validates Bob's pool **shape** when adding (via `validateChallengePool`)
+- Bob never transmits his secrets
+- Communication secured via TLS
+- Bob can validate his pool section when Alice evolves keystone
+
+## Validation
+
+To verify a keystone timeline:
+
+1. **Replay** from genesis to current frame
+2. **Verify** each proof's hash pre-images match challenges
+3. **Validate** challenge selection matches policy engine rules
+4. **Check** revocation status (if revoked, identity cannot evolve)
+
+Validation helpers:
+*   `validateEvolution()`: Verifies transition from previous to current frame
+*   `validateKeystoneTimeline()`: Replays entire timeline from genesis
+
+## Integration with Sync
+
+Keystones integrate with the sync protocol to provide **session identity**:
+
+*   **Session Keystones**: Ephemeral identities created per sync saga
+*   **Saga Binding**: Session keystone salted with `sagaId`
+*   **Signature Frames**: Each saga frame can be signed with session identity
+
+> [!CAUTION]
+> **🚧 Session identity integration is NOT yet functional.** See [sync README](file:../sync/README.md#session-identity-usesessionidentity) for current status.
+
 ## Implementation
+
 The v1 implementation creates a pure TypeScript, isomorphic, hash-based identity system. It is designed to be "Non-Evil" and "Graph-Native".
+
+**Key Files**:
+*   [keystone-service-v1.mts](file:./keystone-service-v1.mts): Core service implementation
+*   [keystone-types.mts](file:./keystone-types.mts): TypeScript type definitions
+*   [keystone-helpers.mts](file:./keystone-helpers.mts): Utility functions

package/src/keystone/docs/architecture.md

@@ -14,6 +14,33 @@
 *   **Challenge Pool**: A collection of puzzles stored in each Keystone Frame.
 *   **Constraint/Policy Engine**: Logic that determines *which* challenges must be solved to authorize a specific action (Binding, FIFO, Stochastic).
 
+### Foreign Pools (Delegation)
+
+> [!IMPORTANT]
+> **🔀 Keystones support delegation** by embedding challenges from external identities.
+
+**Mechanism**:
+*   **Use Case**: Alice adds Bob's challenge pool to her keystone
+*   **Validation**: Alice validates Bob's pool **shape** when adding (via `validateChallengePool`)
+*   **Signing**: Bob can sign claims on Alice's behalf (limited by `verb` field)
+*   **Trust Model**:
+    - Bob never transmits secrets across network
+    - Communication secured via TLS
+    - Bob can validate his pool section when Alice evolves keystone
+*   **SSO Pattern**: Enables Single Sign-On workflows without shared secrets
+
+**Configuration**:
+```typescript
+{
+  poolId: 'bob-sso',
+  verb: 'login',
+  foreignServerUrl: 'https://bob-server.com',
+  challengeCount: 50
+}
+```
+
+See [KeystoneService_V1.addPools()](file:../keystone-service-v1.mts) for implementation.
+
 ## 3. Policy Engine (Selection & Mitigation)
 
 To prevent replay attacks by Man-in-the-Middle (MITM) actors, the challenges required to sign a frame are selected via a multi-layered pipeline:
@@ -45,7 +72,9 @@ Inputs: `LatestKeystone`, `Claim`, `MasterSecret`.
 1.  **Auto-Routing**: Selects pool based on Verb (e.g., 'revoke').
 2.  **Selection**: Runs Policy Engine.
 3.  **Solving**: Generates solutions.
-4.  **Replenishment**: Adds new challenges (Top-Up) or burns them.
+4.  **Replenishment**: Adds new challenges based on pool's `replenishStrategy`:
+    *   **`'top-up'`**: Refills consumed challenges (default, reusable identity)
+    *   **`'scorched-earth'`**: Burns challenges permanently (revocation, one-time operations)
 
 ### 5.3 Validate
 Inputs: `PreviousFrame`, `CurrentFrame`.

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-adv-multitimelines.respec.mts

@@ -114,6 +114,8 @@ await respecfully(sir, `Multi-round/timeline permutations`, async () => {
         in: 'source',
         name: 'r1_alpha_v0_source', // should be auto-calculated?
     });
+    const alpha_tjpAddr =
+        getTjpAddr({ ibGib: r1_alpha_v0_source.ibGib, defaultIfNone: 'incomingAddr' })!;
 
     // Create v1 (common) - will be synced to dest
     const r1_alpha_v1_source_common = await testTransformer.mut8({
@@ -121,8 +123,6 @@ await respecfully(sir, `Multi-round/timeline permutations`, async () => {
         strField: 'commonField',
         name: 'r1_alpha_v1_source_common'
     });
-    const alpha_tjpAddr =
-        getTjpAddr({ ibGib: r1_alpha_v0_source.ibGib, defaultIfNone: 'incomingAddr' })!;
 
     // #endregion r1 setup
 
@@ -170,7 +170,7 @@ await respecfully(sir, `Multi-round/timeline permutations`, async () => {
     });
 
     // Get alpha_v1_common from destSpace for Round 2
-    const resGetDest = await getFromSpace({ space: destSpace, addr: alpha_tjpAddr });
+    const resGetDest = await getFromSpace({ space: destSpace, addr: r1_alpha_v1_source_common.addr });
     if (!resGetDest.success || !resGetDest.ibGibs || resGetDest.ibGibs.length === 0) {
         throw new Error(`Failed to retrieve alpha from destSpace after sync. (E: 40c67811eba14f729880a46dcbb65126)`);
     }