grafema

Fix RFDB V2 graph data silently not persisting to disk after analysis. Use when: (1) rfdb-server reports "0 nodes, 0 edges" on restart despite successful analysis, (2) segment directories exist but are empty (no .bin files), (3) manifest_index.json shows total_nodes: 0 despite analysis logging 70k+ nodes, (4) Docker builds produce empty graph databases, (5) --clear flag used before analyze command. Root cause: GraphEngineV2::clear() replaces the store with MultiShardStore::ephemeral() which has path: None, causing all flush operations to write to in-memory buffers only.

Fix missing theorem proof terms when analyzing Lean 4 environments via importModules. Use when: (1) ConstantInfo.value? returns none for theorems despite TheoremVal.value being Expr, (2) building code graph / dependency extractor for Lean 4 and getting 0 proof dependency edges, (3) Lean 4.30+ project where theorem proofs appear missing from loaded environment, (4) analyzing Mathlib or any Lean 4 project and proof terms are empty. Root cause: breaking change in Lean 4.30 — value? treats theorems as opaque by default.

Fix silent metadata issues in RFDB node storage. Covers two traps: (1) metadata flattening — nested metadata fields become top-level after serialization, so node.metadata.field is undefined but node.field works. (2) reserved keys — fields named "type", "id", "name", "file", "exported" are silently stripped from metadata by _parseNode() to prevent overwriting top-level node fields.

Grafema release procedure for publishing new versions to npm. Covers happy path, pitfalls, rfdb binary lifecycle, and rollback. Use when user says "release", "publish", "bump version".

Diagnose React + Three.js (or any browser canvas) frame stutter by capturing a CDP CPU profile via Playwright instead of guessing from `[perf]` console logs. Use when: (1) frame time is bad but `[perf]` instrumentation doesn't pinpoint the offender, (2) you've spent more than ~30 minutes "fixing" suspects without measuring, (3) hot paths involve animation systems, allocation bursts, or invisible scene-graph traversal, (4) you need self-time per function with line numbers, not aggregate "render slow". The `console.warn` pattern is good for monitoring; CDP is needed for diagnosis. Covers script template, sourcemap setup so minified function names are decoded, and interactive variant where the user drives the interaction and signals stop via `touch /tmp/<flag>`.

Force `rust-embed` to re-embed assets from `$GRAFEMA_UI_DIST` (or any env-driven path) when cargo's incremental compilation skips the macro re-expansion. Use when: (1) you rebuilt the GUI bundle but the rust-server binary still serves the OLD bundle, (2) `cargo build --release` finishes in seconds (incremental hit) and `strings target/release/binary | grep <new-hash>` finds nothing, (3) any rust-embed pipeline where assets live outside the cargo source tree and are picked up via env var or symlink. Cargo only re-runs the proc macro when the rust file declaring `#[derive(RustEmbed)]` changes — env var changes alone don't trigger it.

Verify which process actually owns a TCP port before assuming your fresh restart succeeded. Use when: (1) you killed an old server and started a new one but behaviour matches the OLD code/data, (2) `pkill -f pattern` returned 0 but old behaviour persists, (3) you embedded a new asset/binary but the served version is stale, (4) any "I just restarted X but I'm getting old results" situation. `pkill -f` matches against the process command line — if the live old process was started with `--port 0` (auto-assigned) and got the port you now want, the pattern won't match it. Always verify with `lsof -i :PORT` before debugging deeper.

Fires after fixing any non-trivial bug or regression. Asks: could the graph have caught this as a guarantee? Pairs with reflection-in-and-on-action — picks up after "earliest catchable signal" and asks the next question: was that signal expressible in graph? Triggers: (1) after any non-trivial bug fix is verified working, (2) after a regression report (something used to work, broke), (3) during step 6 (knowledge extraction) of the workflow, (4) when reflection-on-action surfaces a "would have been catchable" signal. Outcome is a triage decision (graph-reachable? rule expressible? rule sound?) and either a draft Linear issue + guarantee proposal, or a recorded "graph capability gap" note. Never auto-creates guarantees.

Decide what to PERSIST in your data structures (graph nodes, DB tables, cache layouts) based on the QUERIES you must answer, not the DEFINITIONS that justify the data. Definitions tell you logical identity; storage strategy is independent. Materializing every definitional component leads to O(N×M) blow-ups that masquerade as memory leaks. Use when: (1) designing a new graph-node type, edge type, DB table, or cache layout; (2) about to name a `subgraph` / `comprises` / `members` / `contains` collection on a parent entity; (3) memory growth proportional to (entities × per-entity-elements); (4) "memory leak" debugging that survives multiple targeted patches — the leak may be storage shape, not retention; (5) pre-implementation sketch includes "for each X, store all reached nodes"; (6) research/spec doc says "X = ⟨A, B, C⟩" and you're tempted to make it three storage edges per X.

Continuous self-reflection routine combining Schön (reflection-in-action / reflection-on-action) and Mezirow (content / process / premise) levels, anchored on KAMI values (val-002 глубина, val-007 честность перед собой, принцип 1 правда, принцип 2 нулевая толерантность к бреду). Triggers FIRE DURING THE TURN, not at end. Use when: (1) about to make a 2nd+ patch attempt at the same problem, (2) user pushes back with "стоп / нет / опять / так, ещё раз / не то / пиздёж", (3) noticing self drifting into "I think that..." without evidence, (4) about to report "готово", (5) copying a pattern from one place to another, (6) task took >2× expected time. Embeds scientific method (explicit hypotheses + falsifiability + prediction-first + alternatives) as substrate for premise-level reflection, not as ceremony.

RFDB server becomes unresponsive (60s+ timeouts) during enricher addEdges write storms. Use when: (1) RFDB CPU spikes to 60-90% after addEdges calls; (2) subsequent reads time out at 60s; (3) server stays catatonic for 5-15 min after a write storm; (4) Tokio main thread parked (write-lock contention). Root cause: add_edges() calls maybe_auto_flush() which has a memory-pressure path that fires on NODE count — not edge count — and holds the exclusive write lock during disk I/O. Fix: separate maybe_auto_flush_edges() uses byte-limit only.

Fix stale Haskell analyzer binaries silently being used by the orchestrator even after a successful rebuild. Use when: (1) modified `packages/js-analyzer/` or other Haskell analyzer source, ran `scripts/build-native.sh ... cabal install`, but a subsequent `grafema analyze` shows old behavior (missing new edges, no new node types, etc.), (2) `~/.cabal/bin/grafema-analyzer` has fresh timestamp but `grafema analyze` produces output as if the change didn't happen, (3) a test verifying new analyzer output passes locally in unit tests but fails in end-to-end runs that go through the orchestrator. Root cause: the Rust orchestrator's `resolve_binary` checks `~/.grafema/bin/<name>` BEFORE `~/.cabal/bin/<name>`, so any stale copy that was once installed there (possibly months ago) shadows the fresh `cabal install` output.

Fix nodes silently disappearing from RFDB when an enricher or post-resolution pass writes new nodes via BatchHandle. Use when: (1) writing a TypeScript enricher that should ADD nodes/edges to existing files, (2) after calling `client.createBatch()` + `batch.addNode({file: 'X', ...})` + `batch.commit()` the original nodes in file X have vanished, (3) tests that load a graph fixture, run an enricher, then query original nodes get empty results, (4) a verification step shows expected nodes pre-enrichment but 0 post-enrichment. Root cause: `BatchHandle.commit()` invokes RFDB's `commit_batch` which AUTO-POPULATES `changed_files` from each added node's `file` field, then the server DELETES all existing nodes whose `file` matches before inserting new ones — file-level upsert semantics. This is correct for the JS/Haskell analyzers (which fully re-emit a file's contents) but catastrophic for enrichers that only ADD to existing files.

Fix silent incorrect results in RFDB Datalog queries that share a variable between two edge atoms on opposite ends (e.g. self-join patterns like `edge(M, C, "T1"), edge(C, M, "T2")`). Use when: (1) a Datalog rule returns rows that look structurally wrong (e.g. a self-loop rule reports hits but pinning M to each reported id refutes the edge existence), (2) Cypher `MATCH (m)-[:R1]->(c)-[:R2]->(m)` returns the same bogus rows (engine-level bug, not Datalog-specific), (3) results change when you bind one variable explicitly vs. leave it free. Root cause: hash- join fast path in `eval_edge_hash_join` / `eval_incoming_hash_join` unconditionally rebinds the non-key Term::Var without checking whether the variable is already bound in the current row.

Fix intermittent `{:no_translation, :unicode, :latin1}` crashes in Elixir escript daemons that use length-prefixed framed IPC on stdin/stdout. Use when: (1) daemon worker crashes only on some input files, usually ones with non-ASCII bytes (kanji, cyrillic, emoji); (2) error surfaces as `Protocol error` from daemon's error branch or as garbled frame-length bytes seen by the orchestrator/client side; (3) standalone one-shot mode works fine on the same input but multi-request daemon mode fails; (4) `IO.binread(:stdio, N)` returns `{:error, {:no_translation, :unicode, :latin1}}` despite the "bin" prefix suggesting it should be encoding-agnostic. Root cause is the escript default `:standard_io` encoding — it's `:unicode`, and `IO.binread` still routes through the io_server, which translates bytes to codepoints and errors when raw binary frames contain invalid UTF-8 sequences.

Design guide + benchmarked pitfalls for building Monte-Carlo / Simulated Annealing refinement layers on top of greedy hex-grid layouts for code visualization (packages/gui/src/store/hexLayout.ts, sandbox/hex-sandbox, future Rust ports). Use when: (1) planning to add MC/SA on top of an existing hex-grid pack, (2) deciding whether a simpler SA would match a hierarchical MC with force-directed + chain drag, (3) budgeting wall-clock for million-node cold-start, (4) debugging "blob turns Swiss-cheese" or "folders stop nucleating" during MC refinement, (5) choosing between folder cohesion and raw Σ-link-length as cost function. Contains four hard-won, quantified lessons and anti-patterns that would take a full day of experiments to rediscover.

Compute a unified outer hull around a group of hex tiles that includes multiple disconnected sub-clusters separated by 1-tile gaps. Use when: (1) rendering nested hierarchy hulls (e.g. "package" hull wrapping multiple "sub-region" hex islands), (2) the naive boundary trace outlines each island separately instead of as one bag, (3) flood-fill from outside walks THROUGH the 1-hex gaps and marks them exterior, (4) heuristic "non-adjacent same-group neighbours" over-fills L-shape concavities, (5) axial-only opposite-pair filling misses non-axial bridges between islands. Solution: morphological close (dilate + erode) on the hex grid — fills exactly the interior 1-hex gaps without affecting exterior corners, then trace boundary on the closed shape.

Fix scattered/torn regions in hex-grid simulated annealing layouts that use "competitive flood-fill" (one tile per region per outer iteration). Use when: (1) regions of >20 tiles end up dispersed instead of forming compact blobs, (2) maxDist/sqrt(N) dispersion ratio is 10×+ worse than the ideal compact blob, (3) tiles assigned to one region show up in multiple disconnected fragments across the layout, (4) the visualization has a "trypophobia ring" pattern at the perimeter where some regions spill into a perimeter spiral, (5) an overflow spiral fallback exists in the layout code and frequently kicks in for large regions, (6) bigger regions look worse than smaller ones (small regions stay compact, big ones shred). Root cause: interleaved competitive flood-fill (round-robin one tile at a time across all regions) lets large regions get boxed in by neighbors before they finish growing — the unfilled remainder is dumped into the overflow spiral at the perimeter, far from the seed. Fix: replace with sequential regio

Diagnose and fix RFDB data disappearing after compaction, where rfdb-server reports a tiny node count (e.g. "15 nodes") on startup despite manifest_index.json showing hundreds of thousands of nodes and segment files existing on disk. Use when: (1) rfdb-server logs "Default database: N nodes" with N orders of magnitude smaller than recent analysis output, (2) /api/stats returns only the most recent commit's nodes, (3) the issue appears AFTER a compaction event (manifest with l1_node_segments populated and node_segments: []), (4) subsequent commits dropped L1 references. Root cause: ManifestStore::create_manifest() initializes l1_node_segments/l1_edge_segments to Vec::new() instead of cloning from current manifest, so any commit AFTER compaction silently orphans all L1 data even though segment .seg files still exist on disk. Compaction injects L1 fields explicitly after create_manifest, but regular commits do not.

Recover from stale RFDB nodes that survive `commit_batch` cleanup despite having their `file` field listed in `changed_files`. Use when: (1) re-running an enricher/orchestrator step but old data with the same file field stays in the graph, (2) `commit_batch(changed_files=[X], ...)` reports success but a query later still returns nodes with `file = X`, (3) you re-pointed structural nodes (e.g., DIRECTORY/FILE) from a synthetic file path to real file paths and the old synthetic-path nodes won't go away, (4) graph-stream / find_by_type returns a mix of "stale" and "new" nodes for the same logical entity. Root cause: `handle_commit_batch` calls `engine.find_by_attr({file: X})` to enumerate nodes-to-delete, but that query path returns only a PARTIAL set after compaction (L1 segments and the file→nodes index can desync). Workaround: enumerate stale nodes via the TS rfdb client `queryNodes({file: X})` (different code path that finds all of them) and call `deleteNode(id)` per node, then re-commit the intended state.

Speed up Rust development iteration when `cargo build --release` takes 10+ minutes even for one-line edits. Use when: (1) every release rebuild takes minutes despite tiny edits, (2) Cargo.toml has `lto = "fat"` and/or `codegen-units = 1` in `[profile.release]`, (3) you want a production- shaped build for testing without paying the LTO cost on every iteration, (4) you suspect cargo is re-linking the whole binary instead of doing incremental work, (5) developing rfdb/grafema-orchestrator/large Rust binaries where full LTO is enabled for shipped builds. Adds a `fast` profile that inherits release but disables LTO, raises codegen-units, enables incremental compilation — first build still slow because it populates a fresh `target/fast/` dep cache, but every subsequent rebuild drops from ~13 min to ~13 s (≈60×).

How to write a Grafema batch-mode plugin that reads the graph and filesystem, then writes new edges/nodes directly to RFDB. Use when: (1) need to add project-specific edges that generic analyzers can't produce, (2) need to read config files (JSON/YAML) and trace values into code, (3) implementing framework-specific resolvers (Django settings, Express routes, pipeline configs). Covers: grafema.config.yaml plugin config, RFDB field naming (src/dst NOT source/target), addEdges/addNodes API, RFDBServerBackend connection pattern.

SWE-bench pipeline for A/B testing Grafema with Claude Code. Use when: (1) running SWE-bench experiments, (2) comparing baseline vs grafema conditions, (3) evaluating results, (4) debugging container issues.

Fix silent failures when parsing Grafema semantic IDs that are in URI format instead of legacy arrow format. Use when: (1) code splits semantic IDs by "->" but gets the whole string back because IDs are grafema:// URIs, (2) file path extraction from semantic IDs returns empty or wrong values, (3) derived edges (DEPENDS_ON, etc.) produce 0 results despite source edges existing, (4) any code that processes semantic IDs after the analysis pipeline's to_uri_format() has run. The grafema:// URI format uses # fragments with percent-encoded characters instead of -> separators.

Fix Playwright automation failures against code-server (VS Code in browser). Use when: (1) trust dialog blocks all clicks — "monaco-dialog-modal-block intercepts pointer events", (2) button:has-text() finds wrong buttons behind modal dialog, (3) keyboard shortcuts don't work — Meta vs Control inconsistency, (4) VS Code extension activity bar icon not found by aria-label, (5) panels show placeholder text despite extension being "Connected". Covers trust dialog dismissal, keyboard shortcut hybrid mode, extension panel selectors, and database connection verification for Grafema extension.

Verify task completion by demonstrating real value: run the new code on real data, show visible results, find gaps between plan and reality. Not about tests/builds — about proving the feature WORKS end-to-end.

Fix Elixir/Erlang AST processing bugs in Grafema beam-analyzer. Use when: (1) Elixir parser returns MODULE node but 0 functions/calls — body nesting issue, (2) Erlang parser crashes with "cannot convert list to string" on OTP 26+ — location format changed from integer to keyword list, (3) pipe operator |> creates spurious CALL nodes instead of desugared function calls — clause ordering bug, (4) multi-module .ex files return only the first module — missing __block__ handler, (5) installing Erlang/Elixir on macOS with outdated Xcode/Clang.

Analyze codebases using a graph database instead of reading source files. Use when understanding code architecture, finding functions or call patterns, tracing data flow, checking dependencies, or answering "where is X used?" questions. Grafema builds a queryable code graph from static analysis — prefer querying the graph over reading files manually.

Systematic methodology for achieving 100% backward dataflow reachability in a new language. Create gauntlet fixture, write trace, diagnose gaps, fix analyzer/algorithm, iterate to 100%. Language-agnostic process. Use when: (1) adding a new language to Grafema, (2) auditing dataflow coverage for existing language, (3) user says "/dataflow-gauntlet".

Cyclical dogfooding loop: test AI-AGENT-STORIES.md against the live graph, discover new stories, analyze gaps, fix root causes, re-test, write report. Use when: (1) user says "/gap-loop", (2) periodic dogfooding session, (3) after a release or major feature to re-validate stories, (4) before sprint planning to prioritize product gaps.

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.

Extract knowledge (decisions, facts, session metadata) from the current Claude Code session into the Grafema Knowledge Base. Run after completing a task or at any point when substantive knowledge was produced. Follows runbook _ai/runbooks/02-claude-sessions.md.

Activate theoretical foundations context for discussions about Grafema's formal underpinnings, multi-language strategy, cognitive science, and abstract architecture. Use when: (1) discussing formal languages, type theory, abstract interpretation, (2) planning multi-language support, (3) designing metrics or benchmarks, (4) reasoning about completeness and soundness of analysis, (5) positioning Grafema academically.

Build all packages, reinstall VS Code extension, commit and push. Use when: user says "ship", or wants to build+install+commit+push in one go.

Fix GraphSnapshot tests blocking CI on every feature PR. Use when: (1) every PR fails CI with "Snapshot mismatch" despite correct behavior, (2) fixing snapshots requires build → regen → commit → wait CI cycle per PR, (3) snapshot test in test/unit/*.test.js glob breaks on any intentional change, (4) pre-push hook runs pnpm build + snapshots:update on every push (2-3min overhead). Solution: move GraphSnapshot.test.js to test/unit/snapshots/ so it's excluded from the *.test.js glob. Run manually via pnpm snapshots:update when needed.

Run automated QA checks on Grafema VS Code extension via Playwright + MCP cross-validation. Use when: (1) user says "/qa" to start or resume QA session, (2) user wants to validate extension panels against graph data, (3) user wants to re-check previously found bugs after a fix, (4) user wants to run a custom QA task. Requires Docker code-server running.

Fix docker exec hanging when starting background processes (servers, daemons) inside containers. Use when: (1) docker exec never returns despite using & or nohup, (2) background server started in container causes docker exec to hang indefinitely, (3) env_startup_command in SWE-bench or similar frameworks times out, (4) setsid/disown needed for proper process detachment in Docker. Root cause: docker exec tracks ALL processes in the exec session, not just the top-level PID.

Fix Node.js CLI tools crashing inside Docker containers when host-installed node_modules require a newer Node version than the container provides. Use when: (1) "SyntaxError: Invalid regular expression flags" with /v flag in string-width or similar packages, (2) node_modules installed on host with Node 20+ but container has Node 18, (3) `npm install` with file: protocol creates symlinks that break inside Docker, (4) pnpm workspace packages become broken symlinks in containers. Covers version detection, Node binary mounting, and npm install strategies for cross-version compatibility.

Fix node query issues in Grafema tests when nodes have numeric IDs instead of human-readable IDs, or when `type` field is undefined. Use when: (1) queryNodes returns nodes with numeric IDs like "52710336597754872375318185843222727675" instead of semantic IDs like "net:request#__network__", (2) node.type is undefined but node.nodeType has a value, (3) metadata is a JSON string instead of parsed object, (4) tests fail with "Cannot read property 'length' of undefined" after queryNodes. Covers RFDBServerBackend vs RFDBClient distinction and async generator handling.