---
name: ibgib-dependency-graph
description: Detailed guide and patterns for using getDependencyGraph from core-gib to extract dependency graphs, live timelines, and graph nodes across spaces
---

# IbGib Dependency Graph Skill Guide

This skill provides patterns, architecture guidelines, and multi-file operational code samples for extracting and traversing dependency graphs in the `ibgib` codebase using `getDependencyGraph` and related functions in `@ibgib/core-gib`.

---

## 1. Overview & Core Architecture

In the `ibgib` content-addressable DAG system, an `ibgib` references other `ibgibs` through relationship links (`rel8ns`), timelines (`tjp` / time-jump-point), and past history (`past`/`ancestor`).

The authoritative implementation of graph extraction resides in:
📁 `libs/core-gib/src/common/other/graph-helper.mts`

Primary exports:
```typescript
import {
    getDependencyGraph,
    getDeltaDependencyGraph,
    toFlatGraph,
    graphsAreEquivalent,
    GetDependencyGraphOptions,
    GetGraphResult,
} from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';
```

### Return Type: `FlatIbGibGraph`
All graph extraction functions return a flat map (`FlatIbGibGraph` / `GetGraphResult`) structured as:
```typescript
export type FlatIbGibGraph = { [addr: IbGibAddr]: IbGib_V1 };
```
- **Keys**: `IbGibAddr` string (computed via `getIbGibAddr({ ibGib })`).
- **Values**: Complete `IbGib_V1` data structure.
- **Primitives**: Primitive ibgibs (e.g. `gib === GIB` or primitive ibs) are automatically filtered out and excluded from the graph.

---

## 2. Function Signatures & Options

```typescript
export interface GetGraphOptions {
    /** Single source ibGib object */
    ibGib?: IbGib_V1;
    /** Multiple source ibGib objects */
    ibGibs?: IbGib_V1[];
    /** Single source ibGib address string */
    ibGibAddr?: IbGibAddr;
    /** Multiple source ibGib address strings */
    ibGibAddrs?: IbGibAddr[];

    /** Space within which to resolve & fetch missing ibgibs. */
    space: IbGibSpaceAny | null;

    /** 
     * If true, queries space for latest timeline tips and includes newly added rel8d nodes.
     * If false, performs backward-only DAG traversal through past rel8ns.
     */
    live?: boolean;

    /** List of ibGib addresses to skip fetching. */
    skipAddrs?: IbGibAddr[];

    /** Blacklist of relationship names to skip during traversal (e.g. ['dna']). */
    skipRel8nNames?: string[];

    /** Whitelist of relationship names to traverse (e.g. ['comment', 'pic']). */
    onlyRel8nNames?: string[];

    /** Maximum retries when getting addresses from space if not immediately found. */
    maxRetries?: number;

    /** Delay in milliseconds between space fetch retries. */
    msBetweenRetries?: number;
}
```

---

## 3. Real Code Patterns Sampled Across `libs/core-gib/src/sync/`

Below are real usage patterns extracted across 15 distinct files in `libs/core-gib/src/sync/`:

### Pattern 1: Single `ibGib` Object + Dedicated Space
*Sampled from:* `sync-saga-coordinator.mts` (Line 1984), `sync-innerspace-deep-updates.respec.mts` (Line 116), `sync-withid.pingpong.respec.mts` (Line 170)

```typescript
// Fetch full graph for a single starting node within a space
const depGraph = await getDependencyGraph({
    ibGib: rootItemIbGib,
    space: sourceSpace,
});
// Result: depGraph contains { [addr]: ibGib } for rootItemIbGib and all its child dependencies
```

---

### Pattern 2: Array of `ibGibs` Objects
*Sampled from:* `sync-innerspace-dest-ahead.respec.mts` (Line 99), `sync-innerspace-dest-ahead.withid.respec.mts` (Line 127)

```typescript
// Fetch graph for multiple starting objects in a single pass
const initialDepGraph = await getDependencyGraph({
    ibGibs: [version0IbGib, version1IbGib],
    space: sourceSpace,
});
```

---

### Pattern 3: Single `ibGibAddr` String
*Sampled from:* `sync-innerspace-dest-ahead.withid.respec.mts` (Line 207 & 208)

```typescript
// Fetch graph starting from a known address string (automatically fetched from space)
const sourceV2Graph = await getDependencyGraph({
    ibGibAddr: r1_alpha_v2_dest_newer_addr,
    space: sourceSpace,
});

const destV2Graph = await getDependencyGraph({
    ibGibAddr: r1_alpha_v2_dest_newer_addr,
    space: destSpace,
});
```

---

### Pattern 4: Multiple `ibGibAddrs` Strings in `sync-saga-coordinator`
*Sampled from:* `sync-saga-coordinator.mts` (Line 864 & Line 1717)

```typescript
// Used during SyncSaga domain analysis to fetch transitive closures for multiple target addresses
const fullGraph = await getDependencyGraph({
    ibGibAddrs: targetDomainAddrs,
    space: localSpace,
    live: false,
});
```

---

### Pattern 5: Live Timeline Query (`live: true` vs `live: false`)
*Sampled from:* `sync-conflict-text-merge.respec.mts` (Lines 194, 199, 343, 348), `sync-saga-coordinator.mts` (Line 2706)

```typescript
// live: true queries the space's metastones for the latest timeline tips
const liveSourceGraph = await getDependencyGraph({
    ibGib: rootFolderItem,
    space: sourceSpace,
    live: true,
});

// live: false performs historical DAG walk backwards only (no space metastone queries)
const historicalGraph = await getDependencyGraph({
    ibGib: rootFolderItem,
    space: sourceSpace,
    live: false,
});
```

---

### Pattern 6: Comparing Two Graphs (`graphsAreEquivalent`)
*Sampled from:* `sync-conflict-text-merge.respec.mts`, `sync-innerspace-deep-updates.withid.respec.mts`

```typescript
import { graphsAreEquivalent } from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';

const graphsMatch = graphsAreEquivalent({
    graphA: sourceDepGraph,
    graphB: destDepGraph,
});

if (graphsMatch) {
    console.log('Both spaces contain identical dependency graphs.');
}
```

---

### Pattern 7: Computing Delta Graphs (`getDeltaDependencyGraph`)
*Sampled from:* `sync-saga-coordinator.mts` (Line 2706), `graph-helper.mts`

```typescript
import { getDeltaDependencyGraph } from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';

// Finds nodes present in sourceGraph that are NOT present in destGraph
const deltaGraph = await getDeltaDependencyGraph({
    sourceGraph: sourceBranchDepGraph,
    destGraph: targetBranchDepGraph,
});
// deltaGraph contains only the new/differing ibGib nodes
```

---

## 4. Key Operational Nuances & Edge Cases

1. **Space Resolution & Fallback**:
   - `space` is required to resolve missing `ibGib` addresses. If an address in `rel8ns` is not already in memory (`ibGibs` or `gotten`), `getDependencyGraph` calls `space.get({ arg: addr })`.
2. **Primitive IbGib Auto-Filtering**:
   - Primitive ibgibs (where `gib === GIB` or primitive ibs) are automatically ignored and NOT included in `FlatIbGibGraph`.
3. **Timeline Frames vs. Historical Walk**:
   - When branching to a new branch sub-space (`b2s_<newBranch>`), `getDependencyGraph` extracts the flat graph map of all folder, file, and binary nodes.
   - To register timelines in the new branch space: iterate through the graph values, sort by timeline history (`past` / `ancestor`), and call `registerNewIbGib` (or `putInSpace` + `persistTransformResult`) in order so indexing metastones track timeline tips cleanly.