Skip to content

Disentinel/grafema / .claude/skills/grafema-orchestrator-derived-edges

grafema-orchestrator-derived-edges

Verified

Pattern for adding derived edge types in the Grafema Rust orchestrator (main.rs). Use when: (1) need to create new graph edges derived from existing edges (e.g., MODULE-level DEPENDS_ON from IMPORTS_FROM), (2) Datalog joins on large edge sets time out, (3) adding enrichment steps that combine data from multiple resolver outputs, (4) need to understand how resolver outputs flow through the orchestrator pipeline.

FileKindSize
SKILL.mdskill md4.9 KB
---
name: grafema-orchestrator-derived-edges
description: |
  Pattern for adding derived edge types in the Grafema Rust orchestrator (main.rs).
  Use when: (1) need to create new graph edges derived from existing edges (e.g., MODULE-level
  DEPENDS_ON from IMPORTS_FROM), (2) Datalog joins on large edge sets time out,
  (3) adding enrichment steps that combine data from multiple resolver outputs,
  (4) need to understand how resolver outputs flow through the orchestrator pipeline.
author: Claude Code
version: 1.0.0
date: 2026-03-11
---

# Adding Derived Edges in Grafema Orchestrator

## Problem

You need to add a new edge type that is derived from existing edges created by resolvers.
For example, MODULE->MODULE DEPENDS_ON edges derived from IMPORTS_FROM edges that connect
IMPORT_BINDINGs to their target nodes (CLASS, FUNCTION, MODULE).

## Context / Trigger Conditions

- Need to create graph edges that aggregate or transform existing edges
- Datalog joins involving large edge sets (CONTAINS, IMPORTS_FROM) time out
- New edge type requires data from multiple resolver outputs (JS, Haskell, Rust, etc.)

## Why NOT Datalog

A Datalog query like:
```
violation(SrcMod, DstMod) :-
  edge(Src, Dst, "IMPORTS_FROM"),
  edge(SrcMod, Src, "CONTAINS"),
  node(SrcMod, "MODULE"),
  edge(DstMod, Dst, "CONTAINS"),
  node(DstMod, "MODULE").
```
Times out on real codebases (~1,964 IMPORTS_FROM edges × CONTAINS joins). The RFDB
Datalog engine is not optimized for multi-way joins at this scale.

## Solution

Derive edges **in-memory in the orchestrator** after all resolvers complete.

### Step 1: Declare a collector before resolution blocks

```rust
// Before step 8 in main.rs
let mut all_imports_from_edges: Vec<(String, String)> = Vec::new();
```

### Step 2: Build index from analysis results

`FileAnalysis` has `file` and `module_id` fields — use them directly:

```rust
let file_to_module: HashMap<String, String> = results
    .iter()
    .filter_map(|r| r.analysis.as_ref())
    .map(|a| (a.file.clone(), a.module_id.clone()))
    .collect();
```

### Step 3: Collect edges from each resolver output

After each import-related resolver commits to RFDB, collect its IMPORTS_FROM edges:

```rust
for edge in &import_output.edges {
    if edge.edge_type == "IMPORTS_FROM" {
        all_imports_from_edges.push((edge.src.clone(), edge.dst.clone()));
    }
}
```

Do this for ALL language resolvers: JS, Haskell, Rust, Java, Kotlin, Python, JVM cross.

### Step 4: Extract file from semantic ID

Semantic IDs follow the pattern `path/to/file.ts->TYPE->name[scope]`.
File path is always the first segment before `->`:

```rust
let src_file = src_id.split("->").next().unwrap_or("");
```

### Step 5: Derive and deduplicate

```rust
let mut depends_on_pairs: HashSet<(String, String)> = HashSet::new();
for (src_id, dst_id) in &all_imports_from_edges {
    let src_file = src_id.split("->").next().unwrap_or("");
    let dst_file = dst_id.split("->").next().unwrap_or("");
    if let (Some(src_mod), Some(dst_mod)) =
        (file_to_module.get(src_file), file_to_module.get(dst_file))
    {
        if src_mod != dst_mod {
            depends_on_pairs.insert((src_mod.clone(), dst_mod.clone()));
        }
    }
}
```

### Step 6: Commit to RFDB

```rust
let wire_edges: Vec<rfdb::WireEdge> = depends_on_pairs.iter().map(|(src, dst)| {
    rfdb::WireEdge {
        src: src.clone(),
        dst: dst.clone(),
        edge_type: "DEPENDS_ON".to_string(),
        metadata: Some(format!(
            r#"{{"_source":"module-dependencies","_generation":{generation}}}"#
        )),
    }
}).collect();

rfdb.commit_batch(&[], &[], &wire_edges, false).await?;
```

## Key Constraints

1. **Resolvers receive nodes, not edges** — a Haskell/JS resolver cannot query existing
   edges. Derived edges MUST be computed in the orchestrator (Rust) or via batch-mode plugin.

2. **Resolution outputs are scoped** — each resolver's output exists only within its
   `match` arm. Collect edges immediately after each commit, before the pool shuts down.

3. **Metadata stamping** — use `_source` and `_generation` fields. The orchestrator's
   `gc::stamp_edge_metadata()` handles this for resolver outputs, but for manually
   constructed WireEdges, stamp metadata in the JSON string directly.

4. **Placement** — add derived edge computation AFTER all resolvers (including user plugins)
   but BEFORE the summary println. This ensures all source data is available.

## Verification

```bash
cargo build --release  # Must compile clean
cargo test             # All tests pass
```

After re-analysis:
```
query_graph('violation(X) :- edge(X, _, "DEPENDS_ON").')
# Should return MODULE nodes
```

## Notes

- For ~2,000 IMPORTS_FROM edges and ~350 modules, derivation is instant (< 1ms)
- The `file_to_module` map comes from `FileAnalysis.module_id`, not from RFDB queries
- Self-edges (src_mod == dst_mod) are filtered out
- HashSet deduplication handles multiple imports between the same module pair
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall