graph-os-authoring

graph-os-authoring

Purpose: The graph is the third retrieval layer. Authoring it correctly — idempotent extraction, backend-neutral query layer, honest confidence scores — is what makes cos_graph_* tools faster + more accurate than grep. Getting any one of those wrong corrupts the graph silently, and the agent starts trusting hallucinations.

Read when: editing files matching:

• src/core/graph_os/backends/*.py — SQLite (single backend today; Kuzu retired 2026-05-18 after benchmark showed SQLite p99 < 30 ms on 5-hop @ 1M nodes).
• src/core/graph_os/extractors/*.py — Python AST / doc / config extractors.
• src/core/graph_os/tools/*.py — the cos_graph_* MCP tools (also see mcp-tool-authoring).
• src/core/graph_os/tools/reindex_dispatch.py — incremental reindex orchestration.
• src/core/graph_os/types.py — node + edge type definitions (the contract).

Skip when: only querying the graph (use graph-explorer for that).

The Five Hard Contracts

1. UID scheme (immutable across rebuilds)

Every node has a uid that survives reindex. Scheme:

code:file:<path>
code:function:<path>::<name>
code:class:<path>::<name>
code:module:<dotted-name>
doc:file:<path>
doc:heading:<path>#<slug>:<level>
folder:<path>
config:<path>::<key>

Path is repo-relative, POSIX, no leading slash. Never include line numbers in uids — line numbers shift; uids must be stable.

When adding a new node type, extend the registry in src/core/graph_os/types.py and document the uid grammar there. The grammar IS the contract — agents reference uids in saved memories.

2. Idempotent extraction (keyed on uid)

Every extractor MUST be re-runnable. The contract: extracting the same file twice produces the same nodes + edges. Implementation:

def extract(file_path: Path) -> ExtractionResult:
    nodes = []
    edges = []
    for symbol in _walk_ast(file_path):
        nodes.append(GraphNode(
            uid=_make_uid(symbol),  # deterministic from file + symbol name
            kind="function",
            label=symbol.name,
            file_path=str(file_path),
            start_line=symbol.start,
            end_line=symbol.end,
            confidence=1.0,  # AST gives certainty
        ))
        for callee in symbol.callees:
            edges.append(GraphEdge(
                source_uid=nodes[-1].uid,
                target_uid=_resolve_callee_uid(callee, file_path),
                kind="calls",
                confidence=_calc_confidence(callee),  # see §3
            ))
    return ExtractionResult(nodes=nodes, edges=edges)