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.

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

// 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:

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:

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 ->:

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

Step 5: Derive and deduplicate

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

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

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: 322kUpdated 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