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

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

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

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