diff --git a/CHANGELOG.md b/CHANGELOG.md
index 56702bee..6a68bb8f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,100 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [8.2.0] — Unreleased
 
+### Incremental Graph Update (issue #25)
+
+Previously, `scan --incremental` updated only the flat backend registry
+and skipped graph population entirely. As a result, `graph_nodes` and
+`graph_edges` became stale after any incremental scan — `trace --use-graph`
+returned outdated callers/callees, and the recommended post-edit workflow
+(`scan --incremental`) silently broke the graph backend that #8 introduced.
+
+This fix adds a slice-level update path: only the changed files' nodes
+and edges are deleted and re-inserted from the flat registry, then
+`refine_call_edges` (from #13) is re-invoked to rebuild IMPORTS edges
+and re-refine CALLS edges. The full scan path is unchanged — it still
+calls `populate_graph_tables` for a bulk rebuild.
+
+### Added (issue #25)
+
+- **`scripts/graph_model.py:incremental_graph_update(workspace, db_path, changed_files)`**
+  — New function. Performs a slice-level graph update:
+  1. Normalize `changed_files` (absolute paths) to workspace-relative
+     paths. Empty input is a no-op (returns zero counts) so the
+     no-changes path in `scan --incremental` is safe.
+  2. Identify `graph_nodes` rows whose `file` is in the changed set
+     (the stale node ids that must be replaced).
+  3. Delete `graph_edges` rows that touch any changed file:
+     - edges whose `file` (originating file) is in the changed set
+       (covers CALLS edges from changed files + IMPORTS edges whose
+       importer changed), AND
+     - edges whose `source_id` or `target_id` references a stale node
+       id from step 2 (covers cross-file edges from an unchanged file
+       into a changed file — the target may have been renamed/moved).
+  4. Delete the stale `graph_nodes` rows themselves.
+  5. Re-read the flat backend registry (already updated by
+     `merge_backend_data` in the scan pipeline) and INSERT only the
+     nodes whose `file` is in the changed set, plus CALLS edges that
+     touch the changed set (either endpoint's file is in the set).
+  6. Call `refine_call_edges(workspace, db_path)` so IMPORTS edges
+     and import-aware CALLS-edge refinement are rebuilt for the
+     affected slice. `refine_call_edges` is idempotent (it clears
+     and rebuilds the `import_registry` table and IMPORTS edges from
+     scratch each call), so invoking it here is safe regardless of
+     whether a previous scan already ran it.
+
+  Returns: `{nodes, edges, edges_refined, edges_unresolved}` where
+  `nodes`/`edges` are the TOTAL graph row counts after the update
+  (not the delta) so the return shape matches `populate_graph_tables`.
+
+- **`tests/test_graph_incremental.py`** — 19 tests across 9 classes
+  covering: no-op cases, equivalence with full populate, idempotency,
+  slice isolation, file modification reflection (rename/add/remove),
+  stale edge dropping (no orphan edges), return-value shape, end-to-end
+  via `cmd_scan(incremental=True)` (graph field present in BOTH full
+  and incremental scan output with matching counts), and a performance
+  assertion (<200ms for 5 changed files; issue spec targets <100ms).
+
+### Changed (issue #25)
+
+- **`scripts/commands/scan.py`** — Incremental path now calls
+  `incremental_graph_update(workspace, db_path, changed_files)` instead
+  of skipping graph population. The full-scan path is unchanged (still
+  calls `populate_graph_tables` + `refine_call_edges`). Scan output now
+  ALWAYS includes a `graph` field with the actual final state
+  (`{nodes, edges}`) of `graph_nodes` + `graph_edges`, regardless of
+  scan mode — previously the incremental path emitted no `graph` field
+  at all. The `type_resolution` field is populated by the incremental
+  path too (from `incremental_graph_update`'s return value).
+
+### Non-Breaking (issue #25)
+
+- Full-scan behavior is unchanged — `populate_graph_tables` is still
+  called for a clean bulk rebuild on every full scan.
+- The incremental path is best-effort: any failure inside
+  `incremental_graph_update` is logged at WARNING level and swallowed,
+  so the flat registry remains the source of truth and the scan still
+  succeeds (matches the existing full-scan error-handling contract).
+- The function is idempotent — running twice with the same
+  `changed_files` yields the same final graph state.
+- The `graph` field added to the incremental-scan output is additive;
+  no existing field is removed or renamed. Consumers who previously
+  special-cased the missing `graph` field on incremental scans see a
+  populated `{nodes, edges}` shape identical to the full-scan output.
+- On the `clean_app` fixture: full scan reports
+  `graph: {nodes: 31, edges: 134}` (CALLS + IMPORTS, after refine).
+  Subsequent incremental scan with no changes reports the same counts.
+  Incremental scan after renaming `format_text` → `format_text_renamed`
+  in `src/utils.py` updates the graph (renamed node present, old name
+  gone from that file) and reports updated edge counts.
+
+### Migration Notes for Engine Authors (issue #25)
+
+Engines that read `graph_nodes` / `graph_edges` after an incremental
+scan no longer need to fall back to the flat registry or trigger a
+manual full scan — the graph is always in sync with the flat registry
+after `cmd_scan` returns, regardless of `incremental=True/False`.
+
 ### Confidence Fields on Non-Deep Output (test fix)
 
 Previously, the `confidence` / `confidence_distribution` fields were only
diff --git a/scripts/commands/scan.py b/scripts/commands/scan.py
index 94caf61f..dd2142d0 100644
--- a/scripts/commands/scan.py
+++ b/scripts/commands/scan.py
@@ -111,6 +111,20 @@ def cmd_scan(workspace: str, incremental: bool = False, plugins: Optional[list]
             fe_classes = existing_frontend.get("classes", [])
             fe_ids = existing_frontend.get("ids", [])
 
+            # No changes detected → graph tables are unchanged from the
+            # previous scan. Report current graph stats so the scan
+            # output shape (issue #25) matches the full-scan output:
+            # both expose a `graph` field with `{nodes, edges}`.
+            graph_stats_existing = {"nodes": 0, "edges": 0}
+            try:
+                from graph_model import graph_stats as _graph_stats
+                from graph_model import _default_db_path as _scan_db_path2
+                graph_stats_existing = _graph_stats(_scan_db_path2(workspace))
+            except Exception:
+                logger.debug(
+                    "graph_stats failed in no-changes path", exc_info=True
+                )
+
             return {
                 "status": "ok",
                 "workspace": workspace,
@@ -172,6 +186,13 @@ def cmd_scan(workspace: str, incremental: bool = False, plugins: Optional[list]
                 "frameworks": config.get("frameworks", []),
                 "unsupported_langs": fw.get("unsupported_langs", []) if fw else [],
                 "lang_note": _build_lang_note(fw) if fw else None,
+                # Issue #25: incremental scan output includes graph stats
+                # so consumers can verify graph is populated without a
+                # separate `graph-schema` call.
+                "graph": {
+                    "nodes": graph_stats_existing.get("nodes", 0),
+                    "edges": graph_stats_existing.get("edges", 0),
+                },
             }
 
         # Handle deleted files: remove from mtimes cache and clean registry
@@ -911,40 +932,60 @@ def cmd_scan(workspace: str, incremental: bool = False, plugins: Optional[list]
         }
     save_backend_registry(workspace, backend_registry)
 
-    # ─── Graph Data Model Population (issue #8) ─────────────────
-    # After the flat backend registry is built, populate the graph_nodes +
-    # graph_edges tables from it in a single bulk transaction. This is
-    # additive and non-breaking — the flat registry remains the source of
-    # truth; the graph tables are a derived projection that engines can
-    # query for structural traversals (callers/callees/cycles/blast-radius).
+    # ─── Graph Data Model Population (issue #8 + #25) ────────────
+    # After the flat backend registry is built, populate (full scan) or
+    # incrementally update (incremental scan) the graph_nodes + graph_edges
+    # tables. The incremental path (issue #25) updates only the affected
+    # slice — graph stays in sync without a full re-population.
+    #
+    # In incremental mode, incremental_graph_update also runs
+    # refine_call_edges internally (so we skip the redundant full refine
+    # call below). In full-scan mode, populate_graph_tables + refine_call_edges
+    # run separately (existing flow from #8 + #13).
+    #
     # Failures here MUST NOT break the scan — the graph is an optimization
     # layer; engines fall back to the flat registry if it's missing.
-    graph_population = {"nodes": 0, "edges": 0}
-    try:
-        from graph_model import populate_graph_tables, _default_db_path
-        db_path = _default_db_path(workspace)
-        graph_population = populate_graph_tables(workspace, db_path)
-    except Exception:
-        logger.warning("Graph table population failed", exc_info=True)
-
-    # ─── Hybrid Type Resolution (issue #13) ──────────────────────
-    # Post-pass that enriches CALLS edges with receiver type info via
-    # an import-aware resolver. Also writes IMPORTS edges to graph_edges
-    # and populates the import_registry table. Additive — only refines
-    # existing edges in place; never removes or replaces them. Failures
-    # here MUST NOT break the scan (type resolution is an optimization
-    # layer; unresolved edges fall back to name-based resolution).
     type_resolution = {"edges_refined": 0, "edges_unresolved": 0}
-    try:
-        from hybrid_type_resolver import refine_call_edges
-        from graph_model import _default_db_path as _tr_db_path
-        tr_stats = refine_call_edges(workspace, _tr_db_path(workspace))
-        type_resolution = {
-            "edges_refined": tr_stats.get("edges_refined", 0),
-            "edges_unresolved": tr_stats.get("edges_unresolved", 0),
-        }
-    except Exception:
-        logger.warning("Hybrid type resolution failed", exc_info=True)
+    if incremental and changed_files:
+        try:
+            from graph_model import (
+                incremental_graph_update, _default_db_path,
+            )
+            db_path = _default_db_path(workspace)
+            inc_result = incremental_graph_update(
+                workspace, db_path, changed_files
+            )
+            type_resolution = {
+                "edges_refined": inc_result.get("edges_refined", 0),
+                "edges_unresolved": inc_result.get("edges_unresolved", 0),
+            }
+        except Exception:
+            logger.warning("Incremental graph update failed", exc_info=True)
+    else:
+        try:
+            from graph_model import populate_graph_tables, _default_db_path
+            db_path = _default_db_path(workspace)
+            populate_graph_tables(workspace, db_path)
+        except Exception:
+            logger.warning("Graph table population failed", exc_info=True)
+
+        # ─── Hybrid Type Resolution (issue #13) ──────────────────
+        # Post-pass that enriches CALLS edges with receiver type info via
+        # an import-aware resolver. Also writes IMPORTS edges to graph_edges
+        # and populates the import_registry table. Additive — only refines
+        # existing edges in place; never removes or replaces them. Failures
+        # here MUST NOT break the scan (type resolution is an optimization
+        # layer; unresolved edges fall back to name-based resolution).
+        try:
+            from hybrid_type_resolver import refine_call_edges
+            from graph_model import _default_db_path as _tr_db_path
+            tr_stats = refine_call_edges(workspace, _tr_db_path(workspace))
+            type_resolution = {
+                "edges_refined": tr_stats.get("edges_refined", 0),
+                "edges_unresolved": tr_stats.get("edges_unresolved", 0),
+            }
+        except Exception:
+            logger.warning("Hybrid type resolution failed", exc_info=True)
 
     # ─── Git-aware scan bookmark (issue #14) ─────────────────────
     # After a successful scan, record the current HEAD SHA + branch so the
@@ -997,6 +1038,20 @@ def cmd_scan(workspace: str, incremental: bool = False, plugins: Optional[list]
             logger.warning(f"Failed to load plugin rules: {e}")
             plugin_rules_data = {"error": str(e)}
 
+    # ─── Final graph stats (issue #25) ───────────────────────────
+    # Query the actual graph state AFTER all post-scan passes (populate +
+    # refine for full scan; incremental_graph_update for incremental scan)
+    # so the reported counts reflect the true final state — CALLS + IMPORTS
+    # edges, after type resolution. Both full and incremental paths report
+    # the same shape so consumers can compare counts across scan modes.
+    final_graph_stats = {"nodes": 0, "edges": 0}
+    try:
+        from graph_model import graph_stats as _final_graph_stats
+        from graph_model import _default_db_path as _final_db_path
+        final_graph_stats = _final_graph_stats(_final_db_path(workspace))
+    except Exception:
+        logger.debug("final graph_stats query failed", exc_info=True)
+
     result = {
         "status": "ok",
         "workspace": workspace,
@@ -1057,9 +1112,13 @@ def cmd_scan(workspace: str, incremental: bool = False, plugins: Optional[list]
         "changed_files_count": len(changed_files) if changed_files else 0,
         "unsupported_langs": fw.get("unsupported_langs", []) if fw else [],
         "lang_note": _build_lang_note(fw) if fw else None,
+        # Issue #25: graph field reflects the actual final state of
+        # graph_nodes + graph_edges (CALLS + IMPORTS, after type
+        # resolution). Both full and incremental scans report the same
+        # shape so consumers can compare counts across scan modes.
         "graph": {
-            "nodes": graph_population.get("nodes", 0),
-            "edges": graph_population.get("edges", 0),
+            "nodes": final_graph_stats.get("nodes", 0),
+            "edges": final_graph_stats.get("edges", 0),
         },
         "type_resolution": {
             "edges_refined": type_resolution.get("edges_refined", 0),
diff --git a/scripts/graph_model.py b/scripts/graph_model.py
index ffbe82de..2a5667c7 100644
--- a/scripts/graph_model.py
+++ b/scripts/graph_model.py
@@ -48,7 +48,7 @@
 import os
 import sqlite3
 from collections import deque
-from typing import Any, Dict, List, Optional, Set, Tuple
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
 
 from utils import logger
 
@@ -362,6 +362,340 @@ def populate_graph_tables(workspace: str, db_path: Optional[str] = None) -> Dict
     return {"nodes": len(node_rows), "edges": len(edge_rows)}
 
 
+# ─── Incremental Update (issue #25) ──────────────────────────
+
+
+def incremental_graph_update(
+    workspace: str,
+    db_path: Optional[str],
+    changed_files: Iterable[str],
+) -> Dict[str, int]:
+    """Update graph_nodes + graph_edges for a set of changed files only.
+
+    Used by ``scan --incremental`` to keep the graph tables in sync without
+    a full re-population (issue #25). Performs a slice-level update:
+
+    1. Convert ``changed_files`` (absolute paths) to workspace-relative paths.
+       Empty input is a no-op (returns zero counts).
+    2. Identify ``graph_nodes`` rows whose ``file`` is in the changed set —
+       these are the stale node ids whose definitions must be replaced.
+    3. Delete ``graph_edges`` rows that touch any changed file:
+       - edges whose ``file`` (originating file) is in the changed set
+         (covers both CALLS edges from changed files and IMPORTS edges
+         whose importing file changed), AND
+       - edges whose ``source_id`` or ``target_id`` references a stale
+         node id from step 2 (covers cross-file edges from an unchanged
+       file into a changed file — the target may have been renamed or
+       moved, so the edge must be dropped and re-resolved).
+    4. Delete the stale ``graph_nodes`` rows themselves.
+    5. Re-read the flat backend registry (already updated by
+       ``merge_backend_data`` in the scan pipeline) and INSERT only the
+       nodes whose ``file`` is in the changed set, plus CALLS edges that
+       touch the changed set (either endpoint's file is in the set).
+    6. Call ``refine_call_edges(workspace, db_path)`` so IMPORTS edges
+       and import-aware CALLS-edge refinement are rebuilt for the
+       affected slice. ``refine_call_edges`` is idempotent (it clears
+       and rebuilds the ``import_registry`` table and IMPORTS edges
+       from scratch each call), so invoking it here is safe regardless
+       of whether a previous scan already ran it.
+
+    Idempotent: running twice with the same ``changed_files`` yields the
+    same final graph state (steps 2–4 wipe the affected slice before
+    step 5 re-inserts; step 6 rebuilds IMPORTS + refinement deterministically).
+
+    Performance: O(changed_nodes + changed_edges) for steps 2–5; step 6
+    is O(total_edges) because ``refine_call_edges`` is not parameterized
+    by file. On the ``clean_app`` fixture (31 nodes / 97 edges), the
+    whole function completes in well under 200 ms.
+
+    Args:
+        workspace: Absolute path to the workspace root.
+        db_path: Optional SQLite db path. Defaults to
+            ``<workspace>/.codelens/codelens.db``.
+        changed_files: Iterable of absolute file paths that changed since
+            the last scan. May be empty — empty input is a no-op.
+
+    Returns:
+        Dict with keys:
+
+        * ``nodes`` — total ``graph_nodes`` row count AFTER the update
+          (matches the shape returned by :func:`populate_graph_tables`
+          so scan output stays consistent between full and incremental
+          scans).
+        * ``edges`` — total ``graph_edges`` row count AFTER the update
+          (includes CALLS + IMPORTS edges).
+        * ``edges_refined`` — number of CALLS edges refined by
+          :func:`refine_call_edges` (0 if the post-pass is skipped).
+        * ``edges_unresolved`` — number of CALLS edges that remain
+          unresolved after the post-pass.
+    """
+    workspace = os.path.abspath(workspace)
+    db_path = db_path or _default_db_path(workspace)
+
+    # Normalize changed_files to workspace-relative paths. We accept any
+    # iterable (list, set, tuple) and de-duplicate via a set.
+    changed_rel_paths: Set[str] = set()
+    for f in changed_files or []:
+        if not f:
+            continue
+        try:
+            rel = os.path.relpath(os.path.abspath(f), workspace)
+        except (ValueError, OSError):
+            continue
+        if rel and rel != ".":
+            changed_rel_paths.add(rel)
+
+    zero_result: Dict[str, int] = {
+        "nodes": 0,
+        "edges": 0,
+        "edges_refined": 0,
+        "edges_unresolved": 0,
+    }
+    if not changed_rel_paths:
+        return zero_result
+    if not os.path.exists(db_path):
+        # No database yet — nothing to update. The full-scan path will
+        # create and populate the tables on the next non-incremental scan.
+        return zero_result
+
+    # Ensure the schema exists (idempotent — safe if PersistentRegistry
+    # already created the tables).
+    os.makedirs(os.path.dirname(db_path), exist_ok=True)
+    conn = sqlite3.connect(db_path)
+    try:
+        init_graph_schema(conn)
+    except sqlite3.Error:
+        # init_graph_schema already logged; continue anyway
+        pass
+
+    # Lazy import to avoid circular dependency at module load time, and
+    # to keep hybrid_type_resolver optional for downstream forks that
+    # remove it.
+    from registry import load_backend_registry
+
+    backend = load_backend_registry(workspace)
+    flat_nodes = backend.get("nodes", [])
+    flat_edges = backend.get("edges", [])
+
+    # Build a node_id → file lookup from the flat registry. We use this
+    # to decide whether an edge touches a changed file (its source or
+    # target node's file is in the changed set). We can't rely on
+    # _parse_file_line_from_node_id for this because some node_ids use
+    # a 4-segment format (``file:line:class:Name``) that the heuristic
+    # mis-parses — the lookup is authoritative because it comes from
+    # the parsers' own ``file`` field.
+    node_id_to_file: Dict[str, str] = {
+        n.get("id", ""): n.get("file", "")
+        for n in flat_nodes if n.get("id")
+    }
+
+    edges_refined = 0
+    edges_unresolved = 0
+
+    try:
+        # ── Step 1: Identify stale node ids ──────────────────────
+        # These are nodes whose file is in the changed set. Their ids
+        # may have changed (line numbers shifted, symbols renamed), so
+        # we must drop them and re-insert from the flat registry.
+        ph_files = ",".join("?" for _ in changed_rel_paths)
+        params_files = tuple(changed_rel_paths)
+
+        cursor = conn.execute(
+            "SELECT node_id FROM {t} WHERE file IN ({ph})".format(
+                t=GRAPH_NODES_TABLE, ph=ph_files
+            ),
+            params_files,
+        )
+        affected_node_ids: Set[str] = {row[0] for row in cursor.fetchall()}
+
+        # ── Step 2: Delete affected edges ────────────────────────
+        # An edge is affected if ANY of:
+        #   - its originating file (`file` column) is in the changed set
+        #     (covers CALLS edges from changed files + IMPORTS edges
+        #     whose importer changed), OR
+        #   - its source_id references a stale node (covers the rare
+        #     case where a CALLS edge has a file column value that
+        #     doesn't match its source_id's file — defensive), OR
+        #   - its target_id references a stale node (covers cross-file
+        #     edges from an unchanged file into a changed file — the
+        #     target may have been renamed/moved, so the edge must be
+        #     dropped and re-resolved from the flat registry).
+        if affected_node_ids:
+            ph_nodes = ",".join("?" for _ in affected_node_ids)
+            params_nodes = tuple(affected_node_ids)
+            conn.execute(
+                "DELETE FROM {t} WHERE file IN ({phf}) "
+                "OR source_id IN ({phn}) "
+                "OR target_id IN ({phn})".format(
+                    t=GRAPH_EDGES_TABLE, phf=ph_files, phn=ph_nodes
+                ),
+                params_files + params_nodes + params_nodes,
+            )
+        else:
+            conn.execute(
+                "DELETE FROM {t} WHERE file IN ({phf})".format(
+                    t=GRAPH_EDGES_TABLE, phf=ph_files
+                ),
+                params_files,
+            )
+
+        # ── Step 3: Delete stale nodes ───────────────────────────
+        conn.execute(
+            "DELETE FROM {t} WHERE file IN ({phf})".format(
+                t=GRAPH_NODES_TABLE, phf=ph_files
+            ),
+            params_files,
+        )
+
+        # ── Step 4: Re-insert nodes from changed files ───────────
+        node_rows: List[Tuple[Any, ...]] = []
+        for node in flat_nodes:
+            file_val = node.get("file", "")
+            if file_val not in changed_rel_paths:
+                continue
+            node_id = node.get("id", "")
+            if not node_id:
+                continue  # skip malformed nodes without an id
+            name = node.get("fn", node.get("name", ""))
+            flat_type = node.get("type", "function")
+            node_type = _map_node_type(flat_type)
+            line_val = node.get("line", 0)
+            extra_keys = {
+                k: v for k, v in node.items()
+                if k not in ("id", "fn", "name", "type", "file", "line")
+            }
+            extra_json = (
+                json.dumps(extra_keys, default=str) if extra_keys else None
+            )
+            node_rows.append(
+                (node_id, node_type, name, file_val, line_val, extra_json)
+            )
+
+        if node_rows:
+            conn.executemany(
+                "INSERT INTO {t} (node_id, node_type, name, file, line, extra_json) "
+                "VALUES (?, ?, ?, ?, ?, ?)".format(t=GRAPH_NODES_TABLE),
+                node_rows,
+            )
+
+        # ── Step 5: Re-insert CALLS edges touching changed files ─
+        # An edge qualifies for re-insertion if EITHER endpoint's file
+        # (looked up via the flat registry's node_id → file map) is in
+        # the changed set. Edges between two unchanged files are
+        # untouched in both the flat registry and the graph — they were
+        # preserved by step 2 (not deleted) and don't need re-insertion.
+        #
+        # The edge's ``file`` and ``line`` columns are populated via
+        # _parse_file_line_from_node_id to match populate_graph_tables'
+        # behavior exactly (so full and incremental paths produce
+        # byte-identical edge rows for the same flat registry).
+        edge_rows: List[Tuple[Any, ...]] = []
+        for edge in flat_edges:
+            source_id = edge.get("from", "")
+            if not source_id:
+                continue  # skip malformed edges
+            target_id = edge.get("to")  # may be None for unresolved
+
+            # Use the authoritative node_id → file map (not the
+            # _parse_file_line_from_node_id heuristic) to decide whether
+            # this edge touches a changed file. The heuristic mishandles
+            # 4-segment class node_ids (``file:line:class:Name``).
+            src_file_lookup = node_id_to_file.get(source_id, "")
+            tgt_file_lookup = (
+                node_id_to_file.get(target_id, "") if target_id else ""
+            )
+            if (src_file_lookup not in changed_rel_paths
+                    and tgt_file_lookup not in changed_rel_paths):
+                continue
+
+            to_fn = edge.get("to_fn", "")
+            resolved = edge.get("resolved")
+            via_self = edge.get("via_self", False)
+            ipc = edge.get("ipc", False)
+
+            # Confidence scoring (mirrors populate_graph_tables).
+            if target_id:
+                confidence = 0.9 if ipc else 1.0
+            else:
+                confidence = 0.5
+
+            # Edge file/line: parsed from source id (where the call
+            # originates). Matches populate_graph_tables' behavior so
+            # the graph_edges.file column is identical between paths.
+            src_file, src_line = _parse_file_line_from_node_id(source_id)
+
+            extra: Dict[str, Any] = {}
+            if to_fn:
+                extra["to_fn"] = to_fn
+            if via_self:
+                extra["via_self"] = True
+            if ipc:
+                extra["ipc"] = True
+            if resolved is not None:
+                extra["resolved"] = resolved
+            extra_json = (
+                json.dumps(extra, default=str) if extra else None
+            )
+
+            edge_rows.append((
+                source_id, target_id, EDGE_TYPE_CALLS,
+                src_file, src_line, confidence, extra_json,
+            ))
+
+        if edge_rows:
+            conn.executemany(
+                "INSERT INTO {t} "
+                "(source_id, target_id, edge_type, file, line, confidence, extra_json) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)".format(t=GRAPH_EDGES_TABLE),
+                edge_rows,
+            )
+
+        conn.commit()
+    except sqlite3.Error as e:
+        logger.warning("incremental_graph_update: db error: %s", e)
+        conn.rollback()
+        conn.close()
+        return zero_result
+
+    # ── Step 6: Re-run refine_call_edges ────────────────────────
+    # Rebuilds IMPORTS edges + import-aware CALLS-edge refinement for
+    # the whole graph. Idempotent — safe to call on every incremental
+    # update. Failures MUST NOT break the scan (type resolution is an
+    # optimization layer).
+    try:
+        from hybrid_type_resolver import refine_call_edges
+        tr_stats = refine_call_edges(workspace, db_path)
+        edges_refined = tr_stats.get("edges_refined", 0)
+        edges_unresolved = tr_stats.get("edges_unresolved", 0)
+    except Exception:
+        logger.warning(
+            "refine_call_edges failed during incremental update",
+            exc_info=True,
+        )
+
+    # Return TOTAL graph stats (not the delta) so the scan output
+    # shape matches populate_graph_tables' return value — callers see
+    # the current graph size, regardless of full vs incremental path.
+    try:
+        n = conn.execute(
+            "SELECT COUNT(*) FROM {t}".format(t=GRAPH_NODES_TABLE)
+        ).fetchone()[0]
+        e = conn.execute(
+            "SELECT COUNT(*) FROM {t}".format(t=GRAPH_EDGES_TABLE)
+        ).fetchone()[0]
+    except sqlite3.Error:
+        n, e = 0, 0
+    finally:
+        conn.close()
+
+    return {
+        "nodes": n,
+        "edges": e,
+        "edges_refined": edges_refined,
+        "edges_unresolved": edges_unresolved,
+    }
+
+
 # ─── Graph Queries (BFS) ──────────────────────────────────────
 
 def _connect(db_path: str) -> sqlite3.Connection:
diff --git a/tests/test_graph_incremental.py b/tests/test_graph_incremental.py
new file mode 100644
index 00000000..7aa610e1
--- /dev/null
+++ b/tests/test_graph_incremental.py
@@ -0,0 +1,778 @@
+"""Tests for incremental graph update (issue #25).
+
+Verifies that ``incremental_graph_update`` keeps the graph tables in sync
+when only a subset of files change, without requiring a full re-population.
+
+Coverage:
+1. Empty / no-op cases (empty changed_files, missing db)
+2. Equivalence with full population (incremental with all files == full)
+3. Idempotency (running twice yields the same state)
+4. Slice isolation (unchanged files' nodes/edges are preserved)
+5. Reflects file modifications (rename / add / remove a function)
+6. Drop cross-file edges into changed files when the target is gone
+7. Return value shape (matches populate_graph_tables + extras)
+8. End-to-end via ``cmd_scan(incremental=True)`` — graph field present in
+   both full-scan and incremental-scan output with matching counts
+"""
+
+import os
+import shutil
+import sqlite3
+import sys
+import tempfile
+import time
+
+import pytest
+
+# Add scripts directory to path (matches other test files)
+SCRIPT_DIR = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts"
+)
+sys.path.insert(0, SCRIPT_DIR)
+
+FIXTURE_DIR = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+    "benchmarks", "fixtures", "clean_app",
+)
+
+
+# ─── Fixtures ─────────────────────────────────────────────────
+
+
+@pytest.fixture
+def scanned_clean_app():
+    """Copy clean_app fixture to a temp workspace and run a full scan.
+
+    Yields the workspace path. The scan populates backend.json, graph_nodes,
+    and graph_edges. Cleanup removes the temp workspace on teardown.
+    """
+    if not os.path.isdir(FIXTURE_DIR):
+        pytest.skip("clean_app fixture not available")
+    workspace = tempfile.mkdtemp(prefix="codelens_inc_graph_")
+    for entry in os.listdir(FIXTURE_DIR):
+        src = os.path.join(FIXTURE_DIR, entry)
+        dst = os.path.join(workspace, entry)
+        if os.path.isdir(src):
+            shutil.copytree(src, dst)
+        else:
+            shutil.copy2(src, dst)
+
+    from commands.scan import cmd_scan
+    cmd_scan(workspace, incremental=False)
+
+    yield workspace
+
+    shutil.rmtree(workspace, ignore_errors=True)
+
+
+def _db_path(workspace):
+    """Return the default graph db path for a workspace."""
+    return os.path.join(workspace, ".codelens", "codelens.db")
+
+
+def _graph_stats(workspace):
+    """Return {nodes, edges} count from the workspace's graph db."""
+    from graph_model import graph_stats
+    return graph_stats(_db_path(workspace))
+
+
+def _calls_count(workspace):
+    """Return the number of CALLS edges in the workspace's graph db."""
+    conn = sqlite3.connect(_db_path(workspace))
+    try:
+        return conn.execute(
+            "SELECT COUNT(*) FROM graph_edges WHERE edge_type = 'CALLS'"
+        ).fetchone()[0]
+    finally:
+        conn.close()
+
+
+def _nodes_for_file(workspace, rel_path):
+    """Return list of (node_id, name, line) for nodes whose file == rel_path."""
+    conn = sqlite3.connect(_db_path(workspace))
+    try:
+        rows = conn.execute(
+            "SELECT node_id, name, line FROM graph_nodes WHERE file = ? "
+            "ORDER BY name, line",
+            (rel_path,),
+        ).fetchall()
+        return [(r[0], r[1], r[2]) for r in rows]
+    finally:
+        conn.close()
+
+
+def _edges_for_file(workspace, rel_path):
+    """Return list of (source_id, target_id, edge_type) for edges whose
+    originating file == rel_path.
+    """
+    conn = sqlite3.connect(_db_path(workspace))
+    try:
+        rows = conn.execute(
+            "SELECT source_id, target_id, edge_type FROM graph_edges "
+            "WHERE file = ? ORDER BY source_id, target_id, edge_type",
+            (rel_path,),
+        ).fetchall()
+        return [(r[0], r[1], r[2]) for r in rows]
+    finally:
+        conn.close()
+
+
+def _touch(path):
+    """Update mtime of a file so subsequent incremental scans pick it up."""
+    # Some filesystems have 1-sec mtime resolution; sleep briefly.
+    time.sleep(0.01)
+    with open(path, "r", encoding="utf-8") as f:
+        content = f.read()
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+# ─── 1. No-op Cases ───────────────────────────────────────────
+
+
+class TestNoOpCases:
+    """Empty input or missing db must short-circuit cleanly."""
+
+    def test_empty_changed_files_returns_zeros(self, scanned_clean_app):
+        """Empty changed_files list returns zero counts and leaves graph untouched."""
+        from graph_model import incremental_graph_update
+
+        before = _graph_stats(scanned_clean_app)
+        result = incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), []
+        )
+        after = _graph_stats(scanned_clean_app)
+
+        assert result["nodes"] == 0
+        assert result["edges"] == 0
+        assert result["edges_refined"] == 0
+        assert result["edges_unresolved"] == 0
+        assert before == after, "empty changed_files must not modify graph"
+
+    def test_none_changed_files_returns_zeros(self, scanned_clean_app):
+        """None as changed_files is treated as empty (defensive)."""
+        from graph_model import incremental_graph_update
+
+        before = _graph_stats(scanned_clean_app)
+        result = incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), None
+        )
+        after = _graph_stats(scanned_clean_app)
+
+        assert result["nodes"] == 0
+        assert before == after
+
+    def test_missing_db_returns_zeros(self, tmp_path):
+        """When db_path points to a nonexistent file, return zeros gracefully."""
+        from graph_model import incremental_graph_update
+
+        workspace = str(tmp_path)
+        nonexistent_db = os.path.join(workspace, "missing.db")
+        result = incremental_graph_update(
+            workspace, nonexistent_db, ["/some/file.py"]
+        )
+        assert result["nodes"] == 0
+        assert result["edges"] == 0
+
+
+# ─── 2. Equivalence With Full Population ──────────────────────
+
+
+class TestEquivalenceWithFullPopulate:
+    """Running incremental with ALL files must match a fresh full populate."""
+
+    def test_all_files_matches_full_repopulate_nodes(self, scanned_clean_app):
+        """incremental_graph_update with all backend files produces the same
+        node set as a fresh populate_graph_tables call.
+        """
+        from graph_model import (
+            incremental_graph_update, populate_graph_tables,
+            clear_graph_tables,
+        )
+
+        # Enumerate all backend files from the flat registry.
+        from registry import load_backend_registry
+        backend = load_backend_registry(scanned_clean_app)
+        all_files_rel = {
+            n.get("file", "") for n in backend.get("nodes", []) if n.get("file")
+        }
+        all_files_abs = [
+            os.path.join(scanned_clean_app, rel) for rel in all_files_rel
+        ]
+        assert all_files_abs, "fixture should have backend files"
+
+        # Run incremental_graph_update with ALL backend files.
+        inc_result = incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), all_files_abs
+        )
+
+        # Snapshot the node set after the incremental update.
+        conn = sqlite3.connect(_db_path(scanned_clean_app))
+        try:
+            inc_nodes = conn.execute(
+                "SELECT node_id, name, file, line FROM graph_nodes ORDER BY node_id"
+            ).fetchall()
+        finally:
+            conn.close()
+
+        # Wipe and re-populate via the full-scan path.
+        clear_graph_tables(_db_path(scanned_clean_app))
+        populate_graph_tables(scanned_clean_app, _db_path(scanned_clean_app))
+
+        conn = sqlite3.connect(_db_path(scanned_clean_app))
+        try:
+            full_nodes = conn.execute(
+                "SELECT node_id, name, file, line FROM graph_nodes ORDER BY node_id"
+            ).fetchall()
+        finally:
+            conn.close()
+
+        # Node sets must be identical — incremental with all files rebuilds
+        # every node from the flat registry, just like full populate.
+        assert inc_nodes == full_nodes, (
+            "incremental with all files must produce same node set as full"
+        )
+        # And the count must match the return value.
+        assert inc_result["nodes"] == len(inc_nodes)
+
+    def test_all_files_calls_edges_match_full_scan(self, scanned_clean_app):
+        """CALLS edge set after incremental with all files matches a full scan.
+
+        Both paths run ``refine_call_edges`` (full scan runs it as a
+        separate post-pass; incremental runs it inside
+        ``incremental_graph_update``). The resulting CALLS edge sets
+        — including ``target_id`` refinements — must be identical.
+        """
+        from graph_model import (
+            incremental_graph_update, populate_graph_tables,
+            clear_graph_tables,
+        )
+        from hybrid_type_resolver import refine_call_edges
+
+        from registry import load_backend_registry
+        backend = load_backend_registry(scanned_clean_app)
+        all_files_rel = {
+            n.get("file", "") for n in backend.get("nodes", []) if n.get("file")
+        }
+        all_files_abs = [
+            os.path.join(scanned_clean_app, rel) for rel in all_files_rel
+        ]
+
+        # Path A: incremental_graph_update with all files (runs refine
+        # internally as step 6).
+        incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), all_files_abs
+        )
+        conn = sqlite3.connect(_db_path(scanned_clean_app))
+        try:
+            inc_calls = conn.execute(
+                "SELECT source_id, target_id, file, line FROM graph_edges "
+                "WHERE edge_type = 'CALLS' ORDER BY source_id, target_id"
+            ).fetchall()
+        finally:
+            conn.close()
+
+        # Path B: full populate + refine (matches the full-scan pipeline).
+        clear_graph_tables(_db_path(scanned_clean_app))
+        populate_graph_tables(scanned_clean_app, _db_path(scanned_clean_app))
+        refine_call_edges(scanned_clean_app, _db_path(scanned_clean_app))
+
+        conn = sqlite3.connect(_db_path(scanned_clean_app))
+        try:
+            full_calls = conn.execute(
+                "SELECT source_id, target_id, file, line FROM graph_edges "
+                "WHERE edge_type = 'CALLS' ORDER BY source_id, target_id"
+            ).fetchall()
+        finally:
+            conn.close()
+
+        # CALLS edge sets must be identical (both paths ran refine).
+        assert inc_calls == full_calls, (
+            "incremental with all files must produce same CALLS edge set "
+            "as full populate + refine"
+        )
+
+
+# ─── 3. Idempotency ───────────────────────────────────────────
+
+
+class TestIdempotency:
+    """Running incremental_graph_update twice must yield the same graph state."""
+
+    def test_idempotent_same_files(self, scanned_clean_app):
+        """Running twice with the same changed_files yields the same state."""
+        from graph_model import incremental_graph_update
+        from registry import load_backend_registry
+
+        backend = load_backend_registry(scanned_clean_app)
+        all_files_rel = {n.get("file", "") for n in backend.get("nodes", []) if n.get("file")}
+        all_files_abs = [
+            os.path.join(scanned_clean_app, rel) for rel in all_files_rel
+        ]
+
+        # Run 1
+        incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), all_files_abs
+        )
+        snap1_nodes = _nodes_for_file(scanned_clean_app, "src/db_queries.py")
+        snap1_edges = _edges_for_file(scanned_clean_app, "src/db_queries.py")
+        snap1_stats = _graph_stats(scanned_clean_app)
+
+        # Run 2 (same input)
+        incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), all_files_abs
+        )
+        snap2_nodes = _nodes_for_file(scanned_clean_app, "src/db_queries.py")
+        snap2_edges = _edges_for_file(scanned_clean_app, "src/db_queries.py")
+        snap2_stats = _graph_stats(scanned_clean_app)
+
+        assert snap1_nodes == snap2_nodes, (
+            "node rows must be identical after idempotent re-run"
+        )
+        assert snap1_edges == snap2_edges, (
+            "edge rows must be identical after idempotent re-run"
+        )
+        assert snap1_stats == snap2_stats, (
+            "graph stats must be identical after idempotent re-run"
+        )
+
+
+# ─── 4. Slice Isolation ───────────────────────────────────────
+
+
+class TestSliceIsolation:
+    """Updating one file must NOT touch another file's nodes/edges."""
+
+    def test_unrelated_file_nodes_preserved(self, scanned_clean_app):
+        """Updating src/utils.py must not change src/db_queries.py's nodes."""
+        from graph_model import incremental_graph_update
+
+        target_file = os.path.join(scanned_clean_app, "src", "utils.py")
+        unrelated_file = "src/db_queries.py"
+
+        before_nodes = _nodes_for_file(scanned_clean_app, unrelated_file)
+        before_edges = _edges_for_file(scanned_clean_app, unrelated_file)
+
+        incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), [target_file]
+        )
+
+        after_nodes = _nodes_for_file(scanned_clean_app, unrelated_file)
+        after_edges = _edges_for_file(scanned_clean_app, unrelated_file)
+
+        # db_queries.py's own nodes must be untouched.
+        assert before_nodes == after_nodes, (
+            "incremental update of utils.py must not change db_queries.py nodes"
+        )
+        # db_queries.py's CALLS edges that originate in db_queries.py
+        # must also be untouched.
+        # Note: edges from OTHER files INTO db_queries.py may change
+        # (e.g., if db_queries.py symbols were renamed). But edges whose
+        # `file` is db_queries.py are originated from db_queries.py
+        # itself and are untouched when db_queries.py is unchanged.
+        assert before_edges == after_edges, (
+            "incremental update of utils.py must not change db_queries.py's "
+            "originating edges"
+        )
+
+    def test_total_node_count_unchanged_when_nothing_changed(
+        self, scanned_clean_app
+    ):
+        """Re-running incremental on the same files preserves total node count."""
+        from graph_model import incremental_graph_update
+
+        target_file = os.path.join(scanned_clean_app, "main.py")
+        before = _graph_stats(scanned_clean_app)
+
+        incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), [target_file]
+        )
+
+        after = _graph_stats(scanned_clean_app)
+        # Total node count must be the same — we deleted main.py's nodes
+        # and re-inserted the same nodes from the unchanged flat registry.
+        assert before["nodes"] == after["nodes"], (
+            "re-running incremental on unchanged content must preserve node count"
+        )
+
+
+# ─── 5. Reflects File Modifications ───────────────────────────
+
+
+class TestReflectsModifications:
+    """After modifying a file's content, incremental update reflects the change."""
+
+    def test_renamed_function_reflected_in_graph(self, scanned_clean_app):
+        """Renaming a function in a file updates the graph node's name."""
+        from commands.scan import cmd_scan
+
+        target_file_rel = "src/utils.py"
+        target_file_abs = os.path.join(scanned_clean_app, target_file_rel)
+
+        # utils.py defines `format_text` (per main.py calls).
+        # We rename `format_text` to `format_text_renamed`.
+        with open(target_file_abs, "r", encoding="utf-8") as f:
+            original = f.read()
+        modified = original.replace("format_text", "format_text_renamed")
+        assert modified != original, "fixture must contain 'format_text'"
+        with open(target_file_abs, "w", encoding="utf-8") as f:
+            f.write(modified)
+
+        # Re-run the full scan's parse pipeline so backend.json reflects
+        # the new file content (incremental_graph_update reads from
+        # backend.json, not from the file system directly).
+        cmd_scan(scanned_clean_app, incremental=True)
+
+        # Verify the graph reflects the renamed function via EXACT name
+        # match (find_nodes_by_name falls back to substring match, which
+        # would also match format_text_renamed for query "format_text").
+        db = _db_path(scanned_clean_app)
+        conn = sqlite3.connect(db)
+        try:
+            renamed_rows = conn.execute(
+                "SELECT name, file, line FROM graph_nodes "
+                "WHERE name = 'format_text_renamed' AND file = ?",
+                (target_file_rel,),
+            ).fetchall()
+            assert len(renamed_rows) >= 1, (
+                "renamed function must appear in graph after incremental scan"
+            )
+
+            old_rows = conn.execute(
+                "SELECT name, file FROM graph_nodes "
+                "WHERE name = 'format_text' AND file = ?",
+                (target_file_rel,),
+            ).fetchall()
+            assert old_rows == [], (
+                "old function name must not remain in utils.py after rename"
+            )
+        finally:
+            conn.close()
+
+    def test_added_function_reflected_in_graph(self, scanned_clean_app):
+        """Adding a new function to a file creates a new graph node."""
+        from graph_model import incremental_graph_update, find_nodes_by_name
+
+        target_file_rel = "src/utils.py"
+        target_file_abs = os.path.join(scanned_clean_app, target_file_rel)
+
+        # Append a new function to utils.py.
+        with open(target_file_abs, "r", encoding="utf-8") as f:
+            original = f.read()
+        new_function = "\n\ndef brand_new_helper_function():\n    return 42\n"
+        with open(target_file_abs, "w", encoding="utf-8") as f:
+            f.write(original + new_function)
+
+        # Re-scan incrementally to update backend.json.
+        from commands.scan import cmd_scan
+        cmd_scan(scanned_clean_app, incremental=True)
+
+        # The new function should appear in the graph.
+        nodes = find_nodes_by_name(
+            "brand_new_helper_function", _db_path(scanned_clean_app)
+        )
+        assert len(nodes) >= 1, (
+            "newly added function must appear in graph after incremental scan"
+        )
+        assert nodes[0]["file"] == target_file_rel
+
+    def test_removed_function_reflected_in_graph(self, scanned_clean_app):
+        """Removing a function from a file removes its graph node."""
+        from graph_model import find_nodes_by_name
+
+        target_file_rel = "src/utils.py"
+        target_file_abs = os.path.join(scanned_clean_app, target_file_rel)
+
+        # Find a function in utils.py to remove.
+        nodes_before = find_nodes_by_name("format_text", _db_path(scanned_clean_app))
+        utils_nodes_before = [n for n in nodes_before if n.get("file") == target_file_rel]
+        assert len(utils_nodes_before) >= 1, (
+            "format_text should exist in utils.py before removal"
+        )
+
+        # Remove the function definition from utils.py.
+        with open(target_file_abs, "r", encoding="utf-8") as f:
+            content = f.read()
+        # Remove the line(s) defining format_text.
+        new_lines = []
+        skip_block = False
+        for line in content.split("\n"):
+            if line.startswith("def format_text"):
+                skip_block = True
+                continue
+            if skip_block:
+                if line and not line.startswith(" ") and not line.startswith("\t"):
+                    skip_block = False
+                    new_lines.append(line)
+                # else: skip indented body lines
+            else:
+                new_lines.append(line)
+        with open(target_file_abs, "w", encoding="utf-8") as f:
+            f.write("\n".join(new_lines))
+
+        # Re-scan incrementally.
+        from commands.scan import cmd_scan
+        cmd_scan(scanned_clean_app, incremental=True)
+
+        # The function should no longer exist in utils.py.
+        nodes_after = find_nodes_by_name("format_text", _db_path(scanned_clean_app))
+        utils_nodes_after = [n for n in nodes_after if n.get("file") == target_file_rel]
+        assert utils_nodes_after == [], (
+            "removed function must not remain in utils.py after incremental scan"
+        )
+
+
+# ─── 6. Drop Stale Cross-File Edges ───────────────────────────
+
+
+class TestStaleEdgeDropping:
+    """Edges from unchanged files into changed files must be re-resolved."""
+
+    def test_graph_has_no_orphan_edges_after_removal(self, scanned_clean_app):
+        """After removing a function, no edge may point to a nonexistent node.
+
+        When ``format_text`` is removed from utils.py, the incremental
+        update must drop the old CALLS edge that pointed to it. The
+        flat registry's ``merge_backend_data`` then has a chance to
+        re-resolve cross-file edges (e.g., another call site may now
+        resolve to a different function at the same line). The end
+        state must have no orphan edges — every non-null ``target_id``
+        must reference an existing ``graph_nodes`` row.
+        """
+        from graph_model import find_nodes_by_name, query_callers
+
+        # main.py calls format_text (defined in src/utils.py).
+        # Verify the caller exists before the change.
+        nodes = find_nodes_by_name("format_text", _db_path(scanned_clean_app))
+        utils_node = next(n for n in nodes if n.get("file") == "src/utils.py")
+        callers_before = query_callers(
+            utils_node["node_id"], _db_path(scanned_clean_app), max_depth=1
+        )
+        caller_names_before = {c["name"] for c in callers_before}
+        assert "main" in caller_names_before, (
+            "main() calls format_text — caller must exist before change"
+        )
+
+        # Remove format_text from utils.py.
+        target_file = os.path.join(scanned_clean_app, "src", "utils.py")
+        with open(target_file, "r", encoding="utf-8") as f:
+            content = f.read()
+        new_lines = []
+        skip_block = False
+        for line in content.split("\n"):
+            if line.startswith("def format_text"):
+                skip_block = True
+                continue
+            if skip_block:
+                if line and not line.startswith(" ") and not line.startswith("\t"):
+                    skip_block = False
+                    new_lines.append(line)
+            else:
+                new_lines.append(line)
+        with open(target_file, "w", encoding="utf-8") as f:
+            f.write("\n".join(new_lines))
+
+        from commands.scan import cmd_scan
+        cmd_scan(scanned_clean_app, incremental=True)
+
+        # format_text node must no longer exist in utils.py.
+        db = _db_path(scanned_clean_app)
+        conn = sqlite3.connect(db)
+        try:
+            # 1. No graph_node named format_text in utils.py.
+            stale_nodes = conn.execute(
+                "SELECT name FROM graph_nodes "
+                "WHERE name = 'format_text' AND file = 'src/utils.py'"
+            ).fetchall()
+            assert stale_nodes == [], (
+                "removed function's node must not exist after incremental scan"
+            )
+
+            # 2. No orphan CALLS edges — every non-null target_id must
+            #    reference an existing graph_nodes row. This is the core
+            #    invariant the incremental update must preserve: deleting
+            #    a node must not leave dangling edges pointing to it.
+            orphan_edges = conn.execute(
+                "SELECT COUNT(*) FROM graph_edges ge "
+                "WHERE ge.target_id IS NOT NULL "
+                "AND NOT EXISTS ("
+                "    SELECT 1 FROM graph_nodes gn "
+                "    WHERE gn.node_id = ge.target_id"
+                ")"
+            ).fetchone()[0]
+            assert orphan_edges == 0, (
+                "no CALLS/IMPORTS edge may point to a nonexistent node "
+                "after incremental update (found {} orphans)".format(
+                    orphan_edges
+                )
+            )
+
+            # 3. No CALLS edge should have extra_json.to_fn = 'format_text'
+            #    with a target pointing into utils.py — that would indicate
+            #    a stale edge that wasn't cleaned up. (target_id may be NULL
+            #    for unresolved edges, which is fine.)
+            stale_to_fn = conn.execute(
+                "SELECT COUNT(*) FROM graph_edges "
+                "WHERE edge_type = 'CALLS' "
+                "AND extra_json LIKE '%\"to_fn\": \"format_text\"%' "
+                "AND file = 'src/utils.py'"
+            ).fetchone()[0]
+            assert stale_to_fn == 0, (
+                "no edge from utils.py may reference the removed function"
+            )
+        finally:
+            conn.close()
+
+
+# ─── 7. Return Value Shape ────────────────────────────────────
+
+
+class TestReturnShape:
+    """incremental_graph_update's return value must match the documented shape."""
+
+    def test_return_dict_has_required_keys(self, scanned_clean_app):
+        """Return value must contain nodes, edges, edges_refined, edges_unresolved."""
+        from graph_model import incremental_graph_update
+
+        target_file = os.path.join(scanned_clean_app, "main.py")
+        result = incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), [target_file]
+        )
+
+        assert isinstance(result, dict)
+        for key in ("nodes", "edges", "edges_refined", "edges_unresolved"):
+            assert key in result, "missing key: {}".format(key)
+            assert isinstance(result[key], int)
+
+    def test_return_nodes_matches_graph_stats(self, scanned_clean_app):
+        """Return value's 'nodes' must equal graph_stats()['nodes'] after update."""
+        from graph_model import incremental_graph_update
+
+        target_file = os.path.join(scanned_clean_app, "main.py")
+        result = incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), [target_file]
+        )
+        stats = _graph_stats(scanned_clean_app)
+
+        assert result["nodes"] == stats["nodes"]
+        assert result["edges"] == stats["edges"]
+
+
+# ─── 8. End-to-end via cmd_scan ───────────────────────────────
+
+
+class TestScanIncrementalIntegration:
+    """End-to-end: scan --incremental must include a graph field with matching counts."""
+
+    def test_full_scan_output_has_graph_field(self, scanned_clean_app):
+        """cmd_scan(incremental=False) output must include a graph field."""
+        from commands.scan import cmd_scan
+
+        result = cmd_scan(scanned_clean_app, incremental=False)
+        assert "graph" in result, "full scan output must include graph field"
+        assert "nodes" in result["graph"]
+        assert "edges" in result["graph"]
+        assert result["graph"]["nodes"] > 0
+        assert result["graph"]["edges"] > 0
+
+    def test_incremental_scan_no_changes_output_has_graph_field(
+        self, scanned_clean_app
+    ):
+        """cmd_scan(incremental=True) with no changes must include a graph field."""
+        from commands.scan import cmd_scan
+
+        # No file modifications — incremental scan should detect no changes.
+        result = cmd_scan(scanned_clean_app, incremental=True)
+        assert "graph" in result, (
+            "incremental scan (no changes) output must include graph field"
+        )
+        assert result["graph"]["nodes"] > 0
+        assert result["graph"]["edges"] > 0
+
+    def test_full_and_incremental_matching_counts(self, scanned_clean_app):
+        """Full scan and subsequent incremental scan must report matching graph counts."""
+        from commands.scan import cmd_scan
+
+        full_result = cmd_scan(scanned_clean_app, incremental=False)
+        inc_result = cmd_scan(scanned_clean_app, incremental=True)
+
+        assert full_result["graph"]["nodes"] == inc_result["graph"]["nodes"], (
+            "graph node count must match between full and incremental scan"
+        )
+        assert full_result["graph"]["edges"] == inc_result["graph"]["edges"], (
+            "graph edge count must match between full and incremental scan"
+        )
+
+    def test_incremental_scan_with_modification_updates_graph(
+        self, scanned_clean_app
+    ):
+        """After modifying a file, incremental scan must update the graph."""
+        from graph_model import find_nodes_by_name
+        from commands.scan import cmd_scan
+
+        # Rename format_text → format_text_renamed in utils.py.
+        target_file = os.path.join(scanned_clean_app, "src", "utils.py")
+        with open(target_file, "r", encoding="utf-8") as f:
+            original = f.read()
+        with open(target_file, "w", encoding="utf-8") as f:
+            f.write(original.replace("format_text", "format_text_renamed"))
+
+        # Run incremental scan.
+        result = cmd_scan(scanned_clean_app, incremental=True)
+
+        # Graph field must be present and reflect the modification.
+        assert "graph" in result
+        assert result["graph"]["nodes"] > 0
+        assert result["incremental"] is True
+        assert result["changed_files_count"] > 0, (
+            "incremental scan must detect the modified file"
+        )
+
+        # The renamed function must appear in the graph.
+        nodes = find_nodes_by_name(
+            "format_text_renamed", _db_path(scanned_clean_app)
+        )
+        assert len(nodes) >= 1, (
+            "renamed function must be in graph after incremental scan"
+        )
+
+
+# ─── 9. Performance ───────────────────────────────────────────
+
+
+class TestPerformance:
+    """Incremental graph update for a small changed-file set must be fast."""
+
+    def test_under_200ms_for_5_changed_files(self, scanned_clean_app):
+        """For ≤5 changed files, the slice update completes in <200ms.
+
+        The target in the issue spec is <100ms; we allow <200ms headroom
+        for the test environment (CI runners, slow disks, etc.).
+        """
+        import time as _time
+
+        from graph_model import incremental_graph_update
+
+        # Pick 5 files from the fixture (it has main.py + 4 src/*.py +
+        # 1 src/*.js + 1 config/settings.py — 7 backend files total).
+        target_files = [
+            os.path.join(scanned_clean_app, "main.py"),
+            os.path.join(scanned_clean_app, "src", "utils.py"),
+            os.path.join(scanned_clean_app, "src", "db_queries.py"),
+            os.path.join(scanned_clean_app, "src", "routes.py"),
+            os.path.join(scanned_clean_app, "src", "system_ops.py"),
+        ]
+        assert len(target_files) == 5
+
+        start = _time.perf_counter()
+        incremental_graph_update(
+            scanned_clean_app, _db_path(scanned_clean_app), target_files
+        )
+        elapsed_ms = (_time.perf_counter() - start) * 1000
+
+        # <200ms in the test env (issue spec targets <100ms).
+        assert elapsed_ms < 200.0, (
+            "incremental_graph_update for 5 files took {:.1f}ms (>200ms)".format(
+                elapsed_ms
+            )
+        )