Graph DB Writes

When to Use

• Adding or changing any Cypher that writes nodes/relationships/properties, in a graph_db mixin or a scan tool that persists to the graph.

For placing a whole new recon tool (which includes its graph write), use recon-tool-integration; this skill is the graph-write rules it depends on.

Critical Rules

• NEVER add the tenant key to a reference node, and NEVER omit it from an entity node. Entity nodes (per-project findings) MERGE on {<natural_key>, user_id, project_id} - the tenant-isolation triple. A MERGE missing user_id/project_id merges one project's data into another's, silently. Global reference nodes (e.g. CVE) key on their natural id only (MERGE (c:CVE {id: $cve_id})); adding tenant keys there fragments shared data.
• NEVER edit graph_db/neo4j_client.py directly. It is a thin orchestrator that combines the mixins by inheritance. Graph methods live in the mixin for their domain (see the table below).
• NEVER unconditionally SET a field another tool owns. Use ON CREATE SET for provenance/first-writer fields (e.g. source) so a later tool merging the same node does not clobber them; use plain SET only for this tool's own enrichment fields. Reference: graph_db/mixins/graphql_mixin.py:189.
• NEVER collect a field in a tool and not write it to the graph. Every field in the tool's output dict must land on a node property or relationship, or it is silent data loss. If it fits no node, map it to the closest property or say why it is dropped.
• NEVER put a map, or a list of maps, in a property. Neo4j rejects it, so SET v += $props fails the whole node write and the mixin's per-finding except turns that into a silently dropped finding. Flatten first: nuclei's cves arrive as {id,cvss,url} maps and are stored as id strings via nuclei_cve_ids in graph_db/mixins/recon/vuln_mixin.py.
• NEVER delete a finding a person has touched, and NEVER clear findings up front. A scan MERGEs its findings (which refreshes updated_at) and afterwards prunes the ones it did not touch - ingest-then-prune, never clear-then-ingest. A half-failed scan that reported nothing would otherwise empty the project, so the CALLER decides whether to prune and only does so after an ingest that actually produced findings. Nodes an operator muted and ones carrying triage_source = 'human' are never deleted, only stamped stale_since: they hold an operator's mute, verdict and the fix items written against them. A mute a node-filter RULE applied (muted_by starting rule:) is not a person's decision and is pruned like any stale finding. Reference: prune_unseen_findings in graph_db/mixins/base_mixin.py, and the four clears that spare them. A delete that spares muted findings takes the node's write lock (SET n._prune_lock = true REMOVE n._prune_lock) BEFORE it reads n:Muted, or a mute committing in between is deleted with the node. An external agent's MCP mute keeps the owner's id in muted_by, so it is kept like a person's; its muted_channel/muted_token stamp must be REMOVEd by every unmute and cleared by every other mute, or a later mute inherits it.
• NEVER prune a source or host the run could not re-check (circuit breakers). When a data provider was paused or a scan host was skipped, "not seen this run" does NOT mean "gone". The caller passes keep_hosts (anchored regexes, matched against _KEEP_HOST_FIELDS with toStringOrNull, passed as a Cypher parameter) to prune_unseen_findings, and skips the prune entirely for a degraded source. What was cut is recorded on the Domain coverage record — recon_coverage_at, recon_coverage_gaps, recon_skipped_hosts, recon_nuclei_truncated (written by update_graph_coverage in graph_db/mixins/recon/domain_mixin.py). Those four are in the webapp's VOLATILE_PROPERTIES, so they never make a Domain read as "changed" in the Recon Delta.
• NEVER write an unscoped MATCH for an entity node. Uniqueness is the (id, user_id, project_id) triple, so a natural id is NOT unique across the database and MATCH (n {id: $id}) can read or write another project's node. Every read and write carries user_id/project_id; agent-facing queries go through scope_query, never inject_tenant_filter alone.
• ALWAYS reuse an existing node label before inventing one. Discovered hostnames are Subdomain, not a new label. Check graph_db/schema_sections.md first - that is the single declaration of every label, property and relationship.
• ALWAYS declare a new label / relationship / property in ONE place: graph_db/schema_sections.md, then re-seed with python3 tooling/scripts/seed_schema_catalog.py. A uniqueness key also goes in graph_db/schema_keys.py, from which schema.py renders its CREATE CONSTRAINT statements. Do NOT copy the schema into the prompt or into GRAPH.SCHEMA.md: the prompt splices the catalog in at __GRAPH_SCHEMA__, and GRAPH.SCHEMA.md deliberately no longer lists labels at all. Three copies is what drifted, and four tests now fail if you make a fourth. Editing or removing a line there fails test_the_composed_document_still_contains_the_baseline in recon/tests/test_schema_catalog.py (additions pass: it is a CONTAINS check, so a stale golden file can sit unnoticed). Refresh the fixture in the same commit with the command in that test's docstring, then read the fixture diff. Still update NODE_COLORS in webapp/src/app/graph/config/colors.ts, which is presentation, not schema.