feat: add compiler-backed Tetra symbol graph extraction - #2491
Conversation
Register .tetra/.t4 as a single batch extraction surface, validate explicit cross-domain links, and report Tetra coverage without duplicating the compiler grammar. Tests: uv run --with openai pytest -q (3943 passed, 36 skipped)
Keep graph topology optimization while allowing the exact graphify update command to advance built_at_commit for same-head release checks. Tests: uv run pytest -q tests/test_watch.py tests/test_tetra_extraction.py tests/test_knowledge_links.py tests/test_report.py
![graphify-labs[bot]](https://avatars.githubusercontent.com/in/4356270?s=60&v=4){kind=small}
There was a problem hiding this comment.
Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).
Graphify reviewed this change.
Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).
Graphify review — findings
This PR adds a compiler-backed extractor for Tetra source files (.tetra and .t4). - It registers the new extensions in detect.py (as code) and extract.py (dispatch table and language-family map), and adds a new graphify/extractors/tetra.py module that shells out to a tetra/go run compiler, converts a symbol-graph payload into nodes/edges, and caches batch results. - The extract() function is modified to pull Tetra files out of the normal per-file/parallel path and run them through a single whole-corpus batch (extract_tetra_batch), merging results back by source file and threading tetra metadata into the return value. A knowledge_links application step is also wired into build_from_json. - Accompanying test changes cover Tetra batch extraction, watch/incremental-rebuild behavior, and report output (token cost, Tetra coverage). Surface area spans build.py, detect.py, extract.py, the new extractors/tetra.py, plus knowledge_links and report code, along with watch/report/tetra test files.
Worth a look
- Tetra batch cache key ignores files that fail to read, silently reusing stale results —
graphify/extractors/tetra.py· Escalate · medium- agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review
- Non-atomic write-then-replace of tetra cache can leave stale .tmp races between concurrent extractions —
graphify/extractors/tetra.py· Escalate · medium- agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review
Analysis details — impact, health, verification
Impact & health
Graphify review
Impact — 2398 functions depend on the 709 functions this change touches.
Health — this change adds coupling hotspots:
- worse:
extract()— 367 callers, 40 callees - worse:
_rebuild_code()— 89 callers, 51 callees - worse:
build_from_json()— 142 callers, 17 callees - worse:
build_merge()— 29 callers, 12 callees - worse:
extract_files_direct()— 15 callers, 21 callees - worse:
to_wiki()— 33 callers, 7 callees - worse:
generate()— 31 callers, 6 callees - worse:
make_inputs()— 15 callers, 5 callees - …and 5 more
Verification — 2398 functions in the blast radius were not formally verified this run (proofs are advisory here).
Gate & verification
graphify gate
PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.
Advisory (not blocking):
- verification_scope: 2140 function(s) in the blast radius were not formally verified this run
· 3 grounded finding(s) anchored inline below; 10 more finding(s) on lines outside this diff (see the check run).
| return f"L{line}:C{column}" if isinstance(column, int) and column > 0 else f"L{line}" | ||
|
|
||
|
|
||
| def convert_symbol_graph(payload: dict[str, Any], root: Path) -> dict[str, Any]: |
There was a problem hiding this comment.
convert_symbol_graph()
high coupling complexity (Ca·Ce = 12).
Grounded coupling-delta finding (deterministic), not an LLM guess.
| return result | ||
|
|
||
|
|
||
| def extract_tetra_batch( |
There was a problem hiding this comment.
extract_tetra_batch()
fans out to 10 callees (efferent coupling).
Grounded coupling-delta finding (deterministic), not an LLM guess.
| return candidates[0] | ||
|
|
||
|
|
||
| def apply_knowledge_links(G: nx.Graph, root: str | Path | None) -> dict[str, int]: |
There was a problem hiding this comment.
apply_knowledge_links()
6 callers depend on it (afferent coupling).
Grounded coupling-delta finding (deterministic), not an LLM guess.
1 participant
Summary
.tetraand.t4as supported code filestetra inspect symbols --format=jsononce per corpus and maptetra.symbol-graph.v1into Graphify nodes/edgesdocs/contracts/knowledge_graph_links.v1.jsonbuilt_at_commitwhengraphify update .sees commit-only changesSafety and behavior
GRAPHIFY_TETRA_BIN,tetraonPATH, repository self-host fallbackVerification
uv run --with openai pytest -q: 3943 passed, 36 skippeduv run ruff check ...: passed