# ibGib Foundations

This document serves as an onboarding guide and technical reference for the **ibgib** protocol, specifically focusing on the V1 implementation and the "Core" concepts used in `core-gib`.

## 1. Core Primitives (`ts-gib`)

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.

### `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).

### 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[]`).

### 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.

### 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.


## 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>`

### 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).

**[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) 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

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`).
  * async call, MUST USE await
  * can NOT be nested
  * **Important Nuance**: The test runner scans test files for `ifWeMight` (or `respecfullyDear`) to determine which *files* get selected and executed. However, once a file is run, the **entire** file executes. The `ifWeMight` only restricts which results are *reported*. This means that code (and `console.log` statements) in standard `ifWe` blocks in the same file will still run, even though they aren't reported, which can lead to confusing logs. To silence those logs during a run, you may need to temporarily comment out or bypass those test blocks completely.
* **`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.

### 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`.

> [!IMPORTANT]
> Never use "ancestor" to refer to the previous frame in a timeline history. That is the "past". Ancestor implies a fork.

## 3. Synchronization (Sync Saga)

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).

### 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.

## 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.
      * 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)
