Document Graph Cache runtime scheduler architecture

.changeset/faster-godot-class-names.md

@@ -2,4 +2,4 @@
 "@codegraphy-dev/plugin-godot": patch
 ---
 
-Godot class-name indexing no longer runs the full GDScript parser for metadata-only `class_name` discovery. On the CodeGraphy monorepo benchmark, the Godot metadata slice helped move cold indexing from 104.67s to 37.27s and file analysis from 87,918ms to 23,352ms.
+Godot class-name indexing no longer runs the full GDScript parser for metadata-only `class_name` discovery. On the CodeGraphy monorepo benchmark, the Godot metadata slice helped move cold indexing from 104.67s to 37.27s: 67.40s faster, a 64.39% reduction, and 2.81x faster. File analysis improved from 87,918ms to 23,352ms: 64,566ms faster, a 73.44% reduction, and 3.76x faster.

.changeset/faster-graph-cache-and-filtering.md

@@ -3,8 +3,8 @@
 "@codegraphy-dev/extension": patch
 ---
 
-Large CodeGraphy workspaces now index, save, and filter graph data much faster. On the CodeGraphy monorepo benchmark, cold indexing improved from 214.04s to 17.28s, Graph Cache saves improved from 122,757ms to 10,904ms, and the Graph Cache shrank from 64,638,976 bytes to 18,153,472 bytes.
+Large CodeGraphy workspaces now index, save, and filter graph data much faster. On the CodeGraphy monorepo benchmark, cold indexing improved from 214.04s to 17.28s: 196.76s faster, a 91.93% reduction, and 12.39x faster. Graph Cache saves improved from 122,757ms to 10,904ms: 111,853ms faster, a 91.12% reduction, and 11.26x faster. Graph Cache size shrank from 64,638,976 bytes to 18,153,472 bytes: 46,485,504 bytes smaller, a 71.92% reduction, and 3.56x smaller.
 
-The same benchmark now projects the current Visible Graph in 12ms instead of 775ms. Folder-node projection improved from 1,369ms to 32ms, import-edge-off projection improved from 153ms to 7ms, and search projection improved from 781ms to 12ms.
+The same benchmark now projects the current Visible Graph in 12ms instead of 775ms: 763ms faster, a 98.45% reduction, and 64.58x faster. Folder-node projection improved from 1,369ms to 32ms: 1,337ms faster, a 97.66% reduction, and 42.78x faster. Import-edge-off projection improved from 153ms to 7ms: 146ms faster, a 95.42% reduction, and 21.86x faster. Search projection improved from 781ms to 12ms: 769ms faster, a 98.46% reduction, and 65.08x faster.
 
 Graph Cache replay also normalizes cached path separators before checking gitignore rules, so ignored files stay filtered across platforms during warm starts.

.changeset/faster-graph-view-interactions.md

@@ -2,8 +2,8 @@
 "@codegraphy-dev/extension": patch
 ---
 
-Graph View interactions now stay responsive on large workspaces. In the VS Code benchmark, toggling the Imports Graph Scope row improved from a 2,983ms median to 188ms wall clock, with the browser-visible update path measuring 54ms.
+Graph View interactions now stay responsive on large workspaces. In the VS Code benchmark, toggling the Imports Graph Scope row improved from a 2,983ms median to 188ms wall clock: 2,795ms faster, a 93.70% reduction, and 15.87x faster. The browser-visible update path measured 54ms.
 
-Warm Graph View startup improved from 9,917ms to 4,614ms. The latest startup split shows CodeGraphy sends the first graph payload at 1,041ms, then spends most remaining first-ready time in VS Code view and webview frame readiness rather than graph work.
+Warm Graph View startup improved from 9,917ms to 4,614ms: 5,303ms faster, a 53.47% reduction, and 2.15x faster. The latest startup split shows CodeGraphy sends the first graph payload at 1,041ms, then spends most remaining first-ready time in VS Code view and webview frame readiness rather than graph work.
 
 Saved-file updates now stay incremental after the graph has loaded. In the editor-save benchmark, the post-save path measured 39ms from saved-document receipt to request start and 140ms to request completion.

.changeset/faster-material-groups.md

@@ -2,4 +2,4 @@
 "@codegraphy-dev/extension": patch
 ---
 
-Default Graph View groups from Material Icon Theme rules now resolve faster in large workspaces. The measured group computation improved from 66ms to 38ms, and total group publish time improved from 71ms to 39ms.
+Default Graph View groups from Material Icon Theme rules now resolve faster in large workspaces. The measured group computation improved from 66ms to 38ms: 28ms faster, a 42.42% reduction, and 1.74x faster. Total group publish time improved from 71ms to 39ms: 32ms faster, a 45.07% reduction, and 1.82x faster.

.changeset/faster-typescript-aliases.md

@@ -2,4 +2,4 @@
 "@codegraphy-dev/plugin-typescript": patch
 ---
 
-TypeScript alias import analysis now reads `tsconfig` compiler options without enumerating every project file, and it reuses parsed alias configuration until the config changes. On the CodeGraphy monorepo benchmark, this moved cold indexing from 37.27s to 17.28s and file analysis from 23,352ms to 3,697ms.
+TypeScript alias import analysis now reads `tsconfig` compiler options without enumerating every project file, and it reuses parsed alias configuration until the config changes. On the CodeGraphy monorepo benchmark, this moved cold indexing from 37.27s to 17.28s: 19.99s faster, a 53.64% reduction, and 2.16x faster. File analysis improved from 23,352ms to 3,697ms: 19,655ms faster, an 84.17% reduction, and 6.32x faster.

.changeset/snappy-graph-runtime-scheduler.md

@@ -0,0 +1,22 @@
+---
+"@codegraphy-dev/plugin-api": minor
+"@codegraphy-dev/core": patch
+"@codegraphy-dev/extension": patch
+"@codegraphy-dev/plugin-godot": patch
+"@codegraphy-dev/plugin-markdown": patch
+"@codegraphy-dev/plugin-particles": patch
+"@codegraphy-dev/plugin-svelte": patch
+"@codegraphy-dev/plugin-typescript": patch
+"@codegraphy-dev/plugin-unity": patch
+"@codegraphy-dev/plugin-vue": patch
+---
+
+Graph View now separates plugin and projection changes from Graph Cache work more aggressively. Filters, node visibility, edge visibility, node colors, visual plugin settings, and plugin disable toggles update the live graph state without scheduling cache saves or index work.
+
+Plugin metadata now declares whether toggles and plugin-owned settings are visual-only, projection-only, plugin-file analysis, or full-index changes. Built-in plugins provide those declarations as examples for plugin authors. Deterministic scheduler tests verify that a 10-action node/edge visibility burst schedules 0 graph jobs, settings-only plugin data schedules 0 graph jobs, and a 10-action analyzer plugin setting burst coalesces to 1 plugin-file refresh.
+
+Cached Graph Scope and plugin-owned evidence tiers are also reused from runtime memory after the first successful hydration. Toggling a cached symbol tier or enabling a cached analyzer plugin reads Graph Cache once with 0 analysis jobs and 0 cache saves. Later off/on toggles reuse the hydrated tier with 0 additional cache reads until an explicit Re-index resets runtime hydration state. If Graph Cache does not contain the requested tier, CodeGraphy falls back to the targeted analysis lane instead of incorrectly treating file-only cache data as a complete graph.
+
+Graph Cache hydration now keeps baseline runtime memory smaller until symbol or plugin evidence is actually needed. In a current `main` versus PR benchmark on an evidence-rich 37 MB CodeGraphy monorepo Graph Cache, baseline runtime cache size moved from 18,583,676 serialized bytes to 10,781,465 serialized bytes: 7,802,211 bytes less, a 41.98% reduction, and 1.72x smaller. Retained symbol facts moved from 11,631 to 0 until Symbol scope is enabled. Median baseline replay in that same run moved from 343.33ms to 316.56ms: 26.77ms faster, a 7.80% reduction, though the current JSON row format means the main win is retained runtime memory rather than avoiding all row parsing.
+
+Saved-file Graph Cache persistence now patches changed rows atomically instead of rewriting the entire Graph Cache. In the current `main` versus PR benchmark on the 18 MB CodeGraphy monorepo Graph Cache, edit persistence moved from a 25,705ms average full save to a 341ms average one-row patch: 25,364ms faster, a 98.67% reduction, and 75.47x faster. Full Re-index still replaces the complete Graph Cache, while normal file edits delete and upsert only the changed cache rows inside one transaction.

codegraphy.schema.json

@@ -79,6 +79,39 @@
       "type": "array",
       "items": { "type": "string" },
       "description": "Glob patterns to exclude from file discovery by default"
+    },
+    "updateImpact": {
+      "type": "object",
+      "required": ["toggle"],
+      "additionalProperties": false,
+      "properties": {
+        "toggle": {
+          "$ref": "#/definitions/updateImpactLevel",
+          "description": "Impact of enabling or disabling the plugin"
+        },
+        "defaultSetting": {
+          "$ref": "#/definitions/updateImpactLevel",
+          "description": "Fallback impact for plugin-owned settings"
+        },
+        "settings": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/definitions/updateImpactLevel" },
+          "description": "Per plugin-owned setting impact overrides"
+        }
+      },
+      "description": "How plugin toggles and settings affect graph indexing and projection"
+    }
+  },
+  "definitions": {
+    "updateImpactLevel": {
+      "type": "string",
+      "enum": [
+        "view-only",
+        "settings-only",
+        "projection-only",
+        "reanalyze-plugin-files",
+        "requires-full-index"
+      ]
     }
   }
 }

docs/PLUGINS.md

@@ -109,7 +109,7 @@ The `Run Extension` launch config runs `pnpm run build:devhost` before opening t
 
 The Plugins panel is a workspace Plugin ID toggle surface backed by static package metadata. It shows installed package-backed plugins that can be enabled, disabled, and reordered for the current CodeGraphy Workspace. Core runtime internals such as Tree-sitter, and legacy VS Code extension plugin entries without a package backing, are not shown as plugin toggle rows.
 
-Disabling a plugin writes `enabled: false` for that Plugin ID in the workspace `plugins` array and unloads its runtime immediately. Package-owned persisted data may remain on disk, but its Graph View nodes, forces, context menu entries, toolbar create entries, webview injections, and UI slots only render while that Plugin ID is enabled and loaded. The Graph View host broadcasts the refreshed plugin status and contribution state immediately after a toggle. Disabling a plugin rebuilds the Graph View from cached analysis instead of rerunning full Indexing; enabling a plugin refreshes only the plugin-owned analysis tier for supported files, then keeps that tier in Graph Cache so future toggles can reuse it.
+Disabling a plugin writes `enabled: false` for that Plugin ID in the workspace `plugins` array and unloads its runtime immediately. Package-owned persisted data may remain on disk, but its Graph View nodes, forces, context menu entries, toolbar create entries, webview injections, and UI slots only render while that Plugin ID is enabled and loaded. The Graph View host broadcasts the refreshed plugin status and contribution state immediately after a toggle. Disabling a plugin rebuilds the Graph View from cached analysis instead of rerunning full Indexing. Enabling an analyzer plugin first tries to hydrate that plugin-owned evidence tier from Graph Cache into runtime memory; if the tier is missing, CodeGraphy refreshes only the plugin-owned analysis tier for supported files. Once loaded, that tier remains resident for future toggles, and normal file edits patch changed Graph Cache rows instead of resaving the full cache.
 
 When Indexing loads an enabled package, `@codegraphy-dev/core` merges `codegraphy.defaultOptions` from the package manifest with the workspace entry's `options` object. Workspace options win. The merged object is passed to package plugin factories as `factoryOptions.options`, and to `initialize`, `onPreAnalyze`, `onFilesChanged`, and `analyzeFile` as `context.options`, so the same plugin package can run with different settings in different CodeGraphy Workspaces.
 

docs/SETTINGS.md

@@ -424,7 +424,9 @@ Disabling a plugin makes that plugin inactive for the workspace graph surface. I
 
 When several relevant Edge Types are available, built-in Edge Types keep their common-usefulness order: **Imports**, **References**, **Calls**, **Type imports**, **Inherits**, **Loads**, **Nests**, **Contains**, then **Overrides**. Plugin-contributed Edge Types appear after built-ins unless a later product decision defines plugin grouping.
 
-Graph Cache enrichment follows Graph Scope. CodeGraphy caches baseline file nodes and file-level edges first; enabling Symbols or a plugin computes the missing tier and keeps it cached when that scope is turned off again.
+Graph Cache enrichment follows Graph Scope. CodeGraphy caches baseline file nodes and file-level edges first. Graph View loads that baseline into runtime memory first, then hydrates Symbol or plugin-owned evidence only when a scope toggle needs it. Once a tier has been loaded, CodeGraphy keeps it in runtime memory for faster future toggles even if the scope is turned off again.
+
+Normal file edits patch the changed Graph Cache rows atomically. Re-index is the force-refresh path that rebuilds and replaces the complete Graph Cache with the current settings.
 
 ## File discovery settings