@ibgib/core-gib 0.1.47 → 0.1.49

package/ibgib-foundations.md

@@ -6,102 +6,120 @@ This document serves as an onboarding guide and technical reference for the **ib
 
 At its lowest level, anything in the system is an **ibGib**.
 
-*   **ib**: The "Metadata". Often a string like "comment", "pic", or "link". It can be descriptive or functional (e.g., class names).
-*   **gib**: The "Hash". A cryptographic hash (SHA-256 in V1) of the entire ibGib record.
-*   **ib^gib**: The content address. Uniquely identifies a record in the universe.
+* **ib**: The "Metadata". Often a string like "comment", "pic", or "link". It can be descriptive or functional (e.g., class names).
+* **gib**: The "Hash". A cryptographic hash (SHA-256 in V1) of the entire ibGib record.
+* **ib^gib**: The content address. Uniquely identifies a record in the universe.
 
 ### `gib` Nuances: Punctiliar vs. TJP
 The `gib` is more than a single hash; it encodes timeline context.
-*   **Punctiliar Hash**: The hash of *just* the current frame's content. Every ibgib has this.
-*   **TJP Gib (Timeline ID)**: The `gib` of the **Temporal Junction Point (TJP)**—the very first frame (Genesis/Fork) of the timeline.
-*   **Composite Address**: Use `ib^[punctiliar_hash].[tjp_gib]`.
-    *   Example: `comment^<CURRENT_HASH>.<GENESIS_HASH>`
-    *   This allows us to identify *which* timeline a frame belongs to simply by looking at its address.
-    *   The `tjp` frame itself has a single hash (since its punctiliar hash IS the tjp gib).
+* **Punctiliar Hash**: The hash of *just* the current frame's content. Every ibgib has this.
+* **TJP Gib (Timeline ID)**: The `gib` of the **Temporal Junction Point (TJP)**—the very first frame (Genesis/Fork) of the timeline.
+* **Composite Address**: Use `ib^[punctiliar_hash].[tjp_gib]`.
+    * Example: `comment^<CURRENT_HASH>.<GENESIS_HASH>`
+    * This allows us to identify *which* timeline a frame belongs to simply by looking at its address.
+    * The `tjp` frame itself has a single hash (since its punctiliar hash IS the tjp gib).
 
 ### Structure
 An `IbGib_V1` object has two primary payload containers:
-1.  **data**: Intrinsic, immutable properties. (e.g., text content, configuration flags).
-2.  **rel8ns**: Extrinsic, Directed Acyclic Graph (DAG) links to other ibGibs.
-    *   Named edges (e.g., `past`, `ancestor`, `pic`).
-    *   Always stored as an array of addresses (`IbGibAddr[]`).
+1. **data**: Intrinsic, immutable properties. (e.g., text content, configuration flags).
+2. **rel8ns**: Extrinsic, Directed Acyclic Graph (DAG) links to other ibGibs.
+    * Named edges (e.g., `past`, `ancestor`, `pic`).
+    * Always stored as an array of addresses (`IbGibAddr[]`).
 
 ### Transforms (The "Verbs")
 State is never mutated in place; it is evolved via transforms.
-*   **[fork](file:../libs/ts-gib/src/V1/transforms/fork.mts)**: Creates a new timeline.
-    *   **Crucial**: Appends to `ancestor` but **CLEARS** the `past` rel8n. This is what births a new timeline.
-*   **[mut8](file:../libs/ts-gib/src/V1/transforms/mut8.mts)** (Mutate): Evolves intrinsic data.
-    *   **Accretive**: By default, it *appends* the new address to the `past` array. It does **not** create a linked list unless `linkedRel8ns` is explicitly used.
-    *   Access the immediate past via `ibgib.rel8ns.past.at(-1)`.
-*   **[rel8](file:../libs/ts-gib/src/V1/transforms/rel8.mts)** (Relate): Evolves extrinsic relationships.
-    *   Also accretive by default.
+* **[fork](file:../libs/ts-gib/src/V1/transforms/fork.mts)**: Creates a new timeline.
+    * **Crucial**: Appends to `ancestor` but **CLEARS** the `past` rel8n. This is what births a new timeline.
+* **[mut8](file:../libs/ts-gib/src/V1/transforms/mut8.mts)** (Mutate): Evolves intrinsic data.
+    * **Accretive**: By default, it *appends* the new address to the `past` array. It does **not** create a linked list unless `linkedRel8ns` is explicitly used.
+    * Access the immediate past via `ibgib.rel8ns.past.at(-1)`.
+* **[rel8](file:../libs/ts-gib/src/V1/transforms/rel8.mts)** (Relate): Evolves extrinsic relationships.
+    * Also accretive by default.
 
 ### DNA (The "How")
 The **`dna`** rel8n is a critical component for distributed consistency.
-*   **Memoization**: It stores the *arguments* used to create a transform (e.g., the specific `dataToAddOrPatch` in a `mut8`).
-*   **In-Structure History**: These arguments are embedded directly in the ibGib structure via the `dna` rel8n.
-*   **Merge Strategy**: When resolving divergent timelines, we don't just compare the final state. We examine the `dna` to understand the *intent* of the divergence.
-    *   *Example*: Two users edit a comment. One fixes a typo, one adds a sentence. By examining the `dna` (the `mut8` args), we can construct a new transform that applies both changes, rather than one overwriting the other.
+* **Memoization**: It stores the *arguments* used to create a transform (e.g., the specific `dataToAddOrPatch` in a `mut8`).
+* **In-Structure History**: These arguments are embedded directly in the ibGib structure via the `dna` rel8n.
+* **Merge Strategy**: When resolving divergent timelines, we don't just compare the final state. We examine the `dna` to understand the *intent* of the divergence.
+    *  *Example*: Two users edit a comment. One fixes a typo, one adds a sentence. By examining the `dna` (the `mut8` args), we can construct a new transform that applies both changes, rather than one overwriting the other.
 
 
 ## 2. Higher-Level Architecture (`core-gib`)
 
 ### Witness Pattern
 The **[Witness](file:src/witness/witness-types.mts)** is the core functional paradigm.
-*   **Concept**: An ibGib that "observes" (witnesses) another ibGib and produces a result.
-*   **Benefits**:
-    *   **Memoization**: Enables memoizing inputs, outputs, and parameters of the witness class itself.
-    *   **Aspect-Oriented Composeability**: Provides a single interaction point for easy composition of behaviors (logging, security, permissions).
-*   **Interface**: `witness(arg: IbGib) -> Promise<IbGib>`
+* **Concept**: An ibGib that "observes" (witnesses) another ibGib and produces a result.
+* **Benefits**:
+    * **Memoization**: Enables memoizing inputs, outputs, and parameters of the witness class itself.
+    * **Aspect-Oriented Composeability**: Provides a single interaction point for easy composition of behaviors (logging, security, permissions).
+* **Interface**: `witness(arg: IbGib) -> Promise<IbGib>`
 
 ### Space Paradigm & Metaspace
 **[Space](file:src/witness/space/space-types.mts)** is a specialized Witness responsible for storage and retrieval.
-*   **Commands**: `put`, `get`, `delete`.
-*   **Locations**: `local`, `sync`, `innerspace` (memory-only/test).
+* **Commands**: `put`, `get`, `delete`.
+* **Locations**: `local`, `sync`, `innerspace` (memory-only/test).
 
 **[Metaspace](file:src/witness/space/metaspace/metaspace-types.mts)**
-*   **Role**: Currently acts as a **Singleton Facade** for the runtime context.
-    *   Does NOT yet actively route "get from any space" requests (though planned).
-    *   Initializes default local spaces.
-    *   **Persistence vs. Indexing**:
-        *   `metaspace.put`: Persists the ibGib to the underlying space(s).
-        *   `metaspace.registerNewIbGib`: Updates the *index* (e.g., "Latest" pointers for timelines) and broadcasts the event via PubSub.
-        *   *Usage*: Always `put` first, then `register` if it's a new timeline tip.
+* **Role**: Currently acts as a **Singleton Facade** for the runtime context.
+    * Does NOT yet actively route "get from any space" requests (though planned).
+    * Initializes default local spaces.
+    * **Persistence vs. Indexing**:
+        * `metaspace.put`: Persists the ibGib to the underlying space(s) via `putInSpace`.
+        * `metaspace.registerNewIbGib`: Updates the *index* (e.g., "Latest" pointers for timelines) and broadcasts the event via `registerNewIbGib` with the pre-configured `fnBroadcast` when metaspace is initialized.
+        *  *Usage*: put first, then register (skipping register only in rare cases).
 
 ### Timeline Facade (`timeline-api`)
 **[Timeline API](file:src/timeline/timeline-api.mts)** acts as a consumer-friendly facade over the raw Witness/Transform calls.
-*   **Purpose**: Simplifies common operations like "Update this timeline with new data" (`mut8Timeline`).
-*   **Abstraction**: Hides the complexity of TJP lookup, generic transforms, and graph traversal.
-
-### respec-gib Test Framework
-
-`respec-gib` is a custom, vastly simplified testing framework. Key points:
-
-- **No CLI arguments**: The test runner does NOT parse command-line arguments like `--testPathPattern` or other Jest-style flags.
-- **Focusing tests**: The ONLY way to focus/filter tests is via `ifWeMight(` regex pattern matching in the test runner script.
-- Commands: Use `npm run test:agent` to run all tests, or modify the `ifWeMight` regex in `src/respec-gib.node.mts` to focus specific test files. (`respec-gib`)
-**[respec-gib](file:src/respec-gib.node.mts)** is the custom BDD-style testing framework.
-*   **Structure**:
-    *   `respecfully`: Top-level organizational block (must `await`).
-    *   `ifWe`: Leaf-node test block (must `await`).
-    *   `iReckon`: Assertions (synchronous, inside `ifWe`).
-    *   *Note*: The test runner crudely regex-searches for `"ifWeMight("`.
+* **Purpose**: Simplifies common operations like "Update this timeline with new data" (`mut8Timeline`).
+* **Abstraction**: Hides the complexity of TJP lookup, generic transforms, and graph traversal.
+
+### *respec-gib* Test Framework
+
+Since `ibgib` has unique execution environment requirements and a high need for custom asynchronous block handling, it uses a custom testing framework located in `@ibgib/helper-gib/dist/respec-gib`. Each lib/app has its own test runner script located in [lib/app]/src/respec-gib.node.mts, e.g., libs/helper-gib/src/respec-gib.node.mts or libs/core-gib/src/respec-gib.node.mts.
+
+Key features include:
+* **`respecfully`**: The equivalent of `describe` or an outer test suite block.
+  * async call, MUST USE await
+  * organizational block
+  * YES can be nested
+* **`ifWe`**: The equivalent of `it`, used for defining a specific test case block.
+  * async call, MUST USE await
+  * can NOT be nested
+* **`ifWeMight`**: A focused test case (equivalent to `fit` or `it.only`). Using this will restrict execution to only the `ifWeMight` block(s) and skip all others.
+  * async call, MUST USE await
+  * can NOT be nested
+* **`iReckon`**: The assertion fluent API (equivalent to `expect`).
+  * sync call, do NOT await
+  * Only specific assertion methods are available compared to other bigger (and funded/helped) testing frameworks:
+  * *Assertions*:
+    * `willEqual(expected)` - Tests deep equality or reference equality.
+    * `isGonnaBe(expected)` - Tests equality.
+    * `isGonnaBeTruthy()` / `isGonnaBeFalsy()` - Tests truthiness.
+    * `isGonnaBeTrue()` / `isGonnaBeFalse()` - Strict equality to true/false.
+    * `isGonnaBeUndefined()` - Strict equality to undefined.
+    * `includes(expected)` - Tests array or substring inclusion.
+  * *Modifiers*:
+    * **`.not`**: Can precede any assertion (e.g., `iReckon(sir, x).not.isGonnaBe(true)`).
+    * **`.asTo(label)`**: Used to add context to the error message (e.g., `iReckon(sir, x).asTo("Checking user ID").willEqual(5)`).
+* Setup and Teardown methods run dynamically per suite context:
+  * `firstOfAll` / `lastOfAll` - Runs once per outer suite.
+  * `firstOfEach` / `lastOfEach` - Runs before/after each inner child (`respecfully` or `ifWe/Might`), or modify the `ifWeMight` regex in `src/respec-gib.node.mts` to focus specific test files.
 
 ### Timelines & Temporal Junction Points (TJPs)
-*   **Accretion vs. Linked List**: Timelines are typically **accretive**. We carry the full history of addresses in the `past` array (`past: [h1, h2, h3...]`).
-    *   *Tradeoff*: Increases metadata size but avoids O(N) network fetches required to traverse a linked list history.
-    *   *Optimization*: Future storage engines will compress this redundancy.
-*   **TJP**: The stable identifier. In code, the TJP's `gib` is often used as the **Lock Scope** to serialize transforms on that timeline.
+* **Accretion vs. Linked List**: Timelines are typically **accretive**. We carry the full history of addresses in the `past` array (`past: [h1, h2, h3...]`).
+  *  *Tradeoff*: Increases metadata size but avoids O(N) network fetches required to traverse a linked list history.
+  *  *Optimization*: Future storage engines will compress this redundancy.
+* **TJP**: The stable identifier. In code, the TJP's `gib` is often used as the **Lock Scope** to serialize transforms on that timeline.
 
 ### IMPORTANT: Ancestor vs. Previous Frame
 It is critical to distinguish between these two relationships:
-*   **Previous Frame (`past`)**: Points to the immediate predecessor in the *same* timeline. This is the "parent" in the Git commit sense.
-    *   *Usage*: `mut8`, `rel8`.
-    *   *Meaning*: "I am the next step in this timeline."
-*   **Ancestor (`ancestor`)**: Points to the source from which a *new* timeline was spawned.
-    *   *Usage*: **ONLY** `fork`.
-    *   *Meaning*: "I am the beginning of a *new* timeline that came from that timeline."
-    *   *Constraint*: A `fork` transform clears the `past` array and adds the source to `ancestor`.
+* **Previous Frame (`past`)**: Points to the immediate predecessor in the *same* timeline. This is the "parent" in the Git commit sense.
+    *  *Usage*: `mut8`, `rel8`.
+    *  *Meaning*: "I am the next step in this timeline."
+* **Ancestor (`ancestor`)**: Points to the source from which a *new* timeline was spawned.
+    *  *Usage*: **ONLY** `fork`.
+    *  *Meaning*: "I am the beginning of a *new* timeline that came from that timeline."
+    *  *Constraint*: A `fork` transform clears the `past` array and adds the source to `ancestor`.
 
 > [!IMPORTANT]
 > Never use "ancestor" to refer to the previous frame in a timeline history. That is the "past". Ancestor implies a fork.
@@ -112,36 +130,38 @@ The Sync Protocol is a **Symmetric, Peer-to-Peer** protocol modeled as a "Saga".
 See: **[Sync README](file:src/sync/README.md)**
 
 ### Core Components
-*   **[SyncSagaIbGib](file:src/sync/sync-types.mts)**: The timeline tracking the sync session itself. Acts as an audit trail.
-*   **[SyncSagaCoordinator](file:src/sync/sync-saga-coordinator.mts)**: The State Machine driver. Code is identical on both "Alice" (Source) and "Bob" (Destination) nodes.
-*   **Message Stones**: Immutable data packets passed between peers (Init, Ack, Delta, Commit).
+* **[SyncSagaIbGib](file:src/sync/sync-types.mts)**: The timeline tracking the sync session itself. Acts as an audit trail.
+* **[SyncSagaCoordinator](file:src/sync/sync-saga-coordinator.mts)**: The State Machine driver. Code is identical on both "Alice" (Source) and "Bob" (Destination) nodes.
+* **Message Stones**: Immutable data packets passed between peers (Init, Ack, Delta, Commit).
 
 ### Protocol Flow
-1.  **Init**: Sender generates a **Knowledge Vector** (KV) summary.
-2.  **Gap Analysis**: Receiver compares KVs.
-    *   Sender behind -> **Push Offer**.
-    *   Sender ahead -> **Delta Request**.
-    *   Diverged -> **Conflict**.
-3.  **Ack**: Receiver sends back lists of needs/offers.
-4.  **Delta/Push**: Data exchange.
-5.  **Commit**: Session finalized.
+1. **Init**: Sender generates a **Knowledge Vector** (KV) summary.
+2. **Gap Analysis**: Receiver compares KVs.
+    * Sender behind -> **Push Offer**.
+    * Sender ahead -> **Delta Request**.
+    * Diverged -> **Conflict**.
+3. **Ack**: Receiver sends back lists of needs/offers.
+4. **Delta/Push**: Data exchange.
+5. **Commit**: Session finalized.
 
 ## 4. Identity (Keystone)
 
 **[Keystone](file:src/keystone/README.md)** is a novel, graph-native identity mechanism using **Hash-Based Cryptography** (Post-Quantum ready).
 
-*   **Concept**: An identity is not a public key; it is a **Timeline** (Keystone). Verification is **Auditability**. To verify "Alice", you replay her Keystone timeline from Genesis to now, verifying proofs at each step.
-*   **Mechanisms**:
-    *   **Hash-Reveal**: Uses schemes similar to **Lamport Signatures** or **Winternitz OTS**, but adapted for the ibGib graph.
-    *   **Merkle DAGs**: Efficiently communicates identity state by only syncing missing graph nodes.
-    *   **Sigma Protocols**: Can support zero-knowledge proofs for authentication without revealing private keys (future).
-*   **Session Identity**: In Sync, we use ephemeral "Session Keystones" to sign the Saga, ensuring the integrity of the sync session without exposing long-term Master Identity keys.
+* **Concept**: An identity is not a public key; it is a **Timeline** (Keystone). Verification is **Auditability**. To verify "Alice", you replay her Keystone timeline from Genesis to now, verifying proofs at each step.
+* **Mechanisms**:
+    * **Hash-Reveal**: Uses schemes similar to **Lamport Signatures** or **Winternitz OTS**, but adapted for the ibGib graph.
+    * **Merkle DAGs**: Efficiently communicates identity state by only syncing missing graph nodes.
+    * **Sigma Protocols**: Can support zero-knowledge proofs for authentication without revealing private keys.
+      * Only partially implemented
+* **Session Identity**: In Sync, we use ephemeral "Session Keystones" to sign the Saga, ensuring the integrity of the sync session without exposing long-term Master Identity keys.
+  * Only partially implemented
 
 ## Reference Links
-*   **Core Types**: [libs/ts-gib/src/types.mts](file:../libs/ts-gib/src/types.mts)
-*   **Transforms**: [libs/ts-gib/src/V1/transforms/](file:../libs/ts-gib/src/V1/transforms/)
-*   **Witness**: [libs/core-gib/src/witness/witness-types.mts](file:src/witness/witness-types.mts)
-*   **Space**: [libs/core-gib/src/witness/space/space-types.mts](file:src/witness/space/space-types.mts)
-*   **Timeline API**: [libs/core-gib/src/timeline/timeline-api.mts](file:src/timeline/timeline-api.mts)
-*   **Sync Coordinator**: [libs/core-gib/src/sync/sync-saga-coordinator.mts](file:src/sync/sync-saga-coordinator.mts)
-*   **Keystone**: [libs/core-gib/src/keystone/README.md](file:src/keystone/README.md)
+* **Core Types**: [libs/ts-gib/src/types.mts](file:../libs/ts-gib/src/types.mts)
+* **Transforms**: [libs/ts-gib/src/V1/transforms/](file:../libs/ts-gib/src/V1/transforms/)
+* **Witness**: [libs/core-gib/src/witness/witness-types.mts](file:src/witness/witness-types.mts)
+* **Space**: [libs/core-gib/src/witness/space/space-types.mts](file:src/witness/space/space-types.mts)
+* **Timeline API**: [libs/core-gib/src/timeline/timeline-api.mts](file:src/timeline/timeline-api.mts)
+* **Sync Coordinator**: [libs/core-gib/src/sync/sync-saga-coordinator.mts](file:src/sync/sync-saga-coordinator.mts)
+* **Keystone**: [libs/core-gib/src/keystone/README.md](file:src/keystone/README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/core-gib",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "description": "ibgib core functionality, including base architecture for witnesses, spaces, apps, robbots, etc., as well as shared utility functions. Node v19+ needed for heavily-used isomorphic webcrypto hashing consumed in both node and browsers.",
   "funding": {
     "type": "individual",

package/src/common/other/ibgib-helper.mts

@@ -1074,3 +1074,42 @@ export async function getIbGibsFromCache_fallbackToSpaces({
         if (logalot) { console.log(`${lc} complete.`); }
     }
 }
+
+/**
+ * naive general purpose helper guard function based off of a given ibgib's
+ * `ib` property.
+ *
+ * uses conventional V1 `ib` schema, expecting space-delimited `ib` with the
+ * first piece being the atom.
+ *
+ * @param x - any object, usually known to be an ibgib
+ * @param atom - the expected atom that determines the type of ibgib
+ * @returns true if `x.ib` contains `atom` and thus is `TIbGib`, else false
+ */
+export function isIbGibWithAtom<TIbGib extends IbGib_V1>(x: any, atom: string): x is TIbGib {
+    const lc = `[${isIbGibWithAtom.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: e946f8ca70b65e6968bd8e78aa473826)`); }
+
+        if (!x.ib) {
+            return false; /* <<<< returns early */
+        }
+
+        if (typeof x.ib !== 'string') {
+            return false; /* <<<< returns early */
+        }
+
+        const [pieceAtom, ...otherPieces] = x.ib.split(' ');
+
+        if (atom !== pieceAtom) {
+            return false; /* <<<< returns early */
+        }
+
+        return true;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/keystone/kdf/kdf-helpers.mts

@@ -39,7 +39,7 @@ export async function deriveKey({
         const strategy = kdfOpts.strategy;
 
         switch (strategy) {
-            case KdfStrategy['recursive-salt-wrap']:
+            case KdfStrategy.recursive_salt_wrap:
                 return await kdf_recursiveSaltWrap({
                     masterSecret,
                     salt: kdfOpts.salt,
@@ -47,7 +47,7 @@ export async function deriveKey({
                     algorithm: kdfOpts.algorithm
                 });
             default:
-                throw new Error(`Unknown KDF strategy: ${strategy}. valid values: ${KDF_STRATEGY_VALID_VALUES.join(', ')} (E: a1b2c3d4e5f6g7h8i9j0)`);
+                throw new Error(`Unknown KDF strategy: ${strategy}. valid values: ${KDF_STRATEGY_VALID_VALUES.join(', ')} (E: c81258e9d9481eb0f88385a825193226)`);
         }
 
     } catch (error) {

package/src/keystone/keystone-config-builder.mts

@@ -244,15 +244,23 @@ interface KeystoneConfigFactoryOptions_Standard {
      * verbs for the pool
      */
     verbs?: string[];
+
+    // only hash challenge type currently implemented
+    type?: KeystoneChallengeType,
     hashAlgorithm?: HashAlgorithm;
     hashRounds?: number;
 }
 
 export function createStandardPoolConfig(opts: KeystoneConfigFactoryOptions_Standard): KeystonePoolConfig {
-    let {
+    if (opts.type && opts.type !== KeystoneChallengeType.hash_reveal_v1) {
+        throw new Error(`invalid type (${opts.type}). Only ${KeystoneChallengeType.hash_reveal_v1} currently implemented. (E: c38616cd7a459149f670418f88766526)`);
+    }
+
+    const {
         salt, id, size, sequential, random, targetBinding, replenishStrategy,
         verbs, hashAlgorithm, hashRounds,
     } = opts;
+
     return KeystoneConfig.hash()
         .withId(id)
         .withSalt(salt)
@@ -272,7 +280,10 @@ export function createStandardPoolConfig(opts: KeystoneConfigFactoryOptions_Stan
 }
 
 export function createHighSecurityPoolConfig(opts: KeystoneConfigFactoryOptions_Standard): KeystonePoolConfig {
-    let {
+    if (opts.type && opts.type !== KeystoneChallengeType.hash_reveal_v1) {
+        throw new Error(`invalid type (${opts.type}). Only ${KeystoneChallengeType.hash_reveal_v1} currently implemented. (E: 09c1f7772bd2a7910f5562b4934d3826)`);
+    }
+    const {
         salt, id, size, sequential, random, targetBinding, replenishStrategy,
         verbs, hashAlgorithm, hashRounds,
     } = opts;

package/src/keystone/keystone-constants.mts

@@ -21,9 +21,14 @@ export const KEYSTONE_VERB_REVOKE = "revoke";
  * @see {@link KeystoneVerb.MANAGE}
  */
 export const KEYSTONE_VERB_MANAGE = "manage";
+/**
+ * @see {@link KeystoneVerb.SIGN}
+ */
+export const KEYSTONE_VERB_SIGN = "sign";
 export type KeystoneVerb =
     | typeof KEYSTONE_VERB_REVOKE
-    | typeof KEYSTONE_VERB_MANAGE;
+    | typeof KEYSTONE_VERB_MANAGE
+    | typeof KEYSTONE_VERB_SIGN;
 
 /**
  * Verbs that describe actions that can be authorized by a Keystone.
@@ -41,8 +46,15 @@ export const KeystoneVerb = {
      * "Root access" to the identity.
      *
      * Basically, this is the verb for the "admin" pool.
+     *
+     * todo: add a separate "add pool" verb
+     * todo: add a one-time mechanism that limits pool use per verb.
      */
     MANAGE: KEYSTONE_VERB_MANAGE,
+    /**
+     * This is the least of all privileges that can actually evolve a keystone.
+     */
+    SIGN: KEYSTONE_VERB_SIGN,
 } satisfies { [key: string]: KeystoneVerb };
 export const KEYSTONE_VERB_VALID_VALUES = Object.values(KeystoneVerb);
 export function isKeystoneVerb(value: string): value is KeystoneVerb {
@@ -51,11 +63,21 @@ export function isKeystoneVerb(value: string): value is KeystoneVerb {
 // #endregion KeystoneVerb enum
 
 /**
- * Standard pool IDs can be conventionally named after their primary verb.
+ * Some standard pool IDs can be conventionally named after their primary verb,
+ * but this is not a requirement.
  */
 export const POOL_ID_REVOKE = KEYSTONE_VERB_REVOKE;
 export const POOL_ID_MANAGE = KEYSTONE_VERB_MANAGE;
 export const POOL_ID_DEFAULT = "default";
+export const POOL_ID_DELEGATE = "delegate";
+/**
+ * **THESE SHOULD ONLY BE USED IN TEMPORARY/SESSION KEYSTONES.**
+ * _this is because a receiver could intercept the stone, DoS participants and
+ * then take over a stone._
+ *
+ * transition pools are used as a temporary mechanism to create one-time management pools for delegates to create their own pools.
+ */
+export const POOL_ID_TRANSITION = "transition";
 
 export const KEYSTONE_CONFIG_DEFAULT_SIZE = 200;
 export const KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL = 2;

package/src/keystone/keystone-helpers.mts

@@ -189,12 +189,14 @@ export function addToBindingMap(
     const firstChar = challengeId.charAt(0).toLowerCase();
     // Validate it is hex
     if (/[0-9a-f]/.test(firstChar)) {
-        if (!map[firstChar]) map[firstChar] = [];
+        if (!map[firstChar]) { map[firstChar] = []; }
         map[firstChar].push(challengeId);
 
         // OPTIONAL: Implement Full Coverage Strategy here?
         // e.g. map[challengeId[1]].push(challengeId) ...
         // For V1, we stick to Native/Implicit bucket (Index 0).
+    } else {
+        throw new Error(`invalid challengeId (${challengeId}). Must start with a hex character. (E: c96ed8460de89e28c801370a0f07f826)`);
     }
 }
 
@@ -968,13 +970,6 @@ export async function validateKeystoneGraph({
         // maybe too defensive but...
         if (!keystoneIbGib) { throw new Error(`(UNEXPECTED) keystoneIbGib falsy? (E: 26482871d529fff6e8899c5d8a6c3826)`); }
 
-        // #region leaving off here
-        // asdf
-        // just implemented validate keystone graph. incorporate this into the
-        // context ibgib, which now has the session ibgib as part of it. each
-        // step in ping pong should validate the entire keystone graph
-
-        // #endregion leaving off here
         const errors: string[] = [];
 
         // first, get the latest if that is the case...
@@ -1048,8 +1043,8 @@ export async function validateKeystoneGraph({
             const keys = Object.keys(orderedKeystonesMap);
             if (keys.length === 0) {
                 throw new Error(`(UNEXPECTED) orderedKeystonesMap empty? (E: d437b80bef58e83a034b28af46278726)`);
-            } else if (keys.length > 0) {
-                // keys.length > 0
+            } else if (keys.length > 1) {
+                // keys.length > 1
                 throw new Error(`(UNEXPECTED) more than one timeline in keystone graph? ATOW (02/19/2026) we are expecting only a single timeline. (E: 66085b14e3887a59c872afd240511f26)`);
             }
             // happy path: exactly one timeline

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,