Add function-scoped Logic visualization

docs/CONTRACT.md

@@ -18,8 +18,8 @@ commit when Git is available; it cannot change repository state.
 - Edge schema: `schemas/edge.schema.json`, version 1.
 - Result envelope: `schemas/result.schema.json`, version 1.
 - Changeset schema: `schemas/changeset.schema.json`, version 1.
-- Index schema: version 1, disposable and reproducible.
-- Core, CLI, and MCP server: version 1.1.0.dev0.
+- Index schema: version 2, disposable and reproducible.
+- Core, CLI, and MCP server: version 1.2.0.dev0.
 - Incremental extraction cache: version 1, disposable and reproducible.
 
 Schema files describe the generic interchange contract. Runtime validation remains responsible for
@@ -104,13 +104,13 @@ random token is part of every accepted URL path. Only `GET` and `HEAD` are suppo
 no-store caching, a restrictive content-security policy, frame denial, MIME sniffing protection,
 and no-referrer policy. The built-in template uses only same-origin JSON endpoints for graph
 overview, bounded search, exact descriptor-category filtering, exact node content, bounded
-incoming-and-outgoing neighborhoods, semantic Flow ancestry, convergence Web context, and one
-node's bounded project-confined source file.
+incoming-and-outgoing neighborhoods, semantic Flow ancestry, convergence Web context, lazy
+function-scoped Logic, and one node's bounded project-confined source file.
 Descriptor filtering accepts only
 family, authority, status, or tag plus one exact value. There is no write endpoint, arbitrary query
 endpoint, static filesystem handler, external asset, or project-selection control.
 
-The `graph-browser@15` template provides mouse-wheel zoom centered on the pointer, left-button drag
+The `graph-browser@16` template provides mouse-wheel zoom centered on the pointer, left-button drag
 pan, explicit zoom-in and zoom-out buttons, a reset-view button, and a live zoom percentage. A
 four-pixel drag threshold defers pointer capture and preserves node activation for ordinary clicks.
 Loading another root node fits the viewport to the returned neighborhood, including a useful
@@ -141,7 +141,7 @@ supported line, TOML, heading, or text anchors. Both side panels support pointer
 resizing. The unblurred full inspector supports native resizing, constrained title-bar dragging,
 and a fixed header/footer surrounding a scrollable body.
 
-The header exposes a Nodes/Flow/Web segmented selector. Nodes displays the complete bounded
+The header exposes a Nodes/Flow/Web/Logic segmented selector. Nodes displays the complete bounded
 neighborhood. Flow displays semantic ancestry ending at the current root. Structural and execution
 edges retain their declared source-to-target direction. Reads, imports, dependencies, inheritance,
 and `tested_by` reverse because their declared target feeds or qualifies the source. Documentation
@@ -151,10 +151,17 @@ direct root-owned members and execution dependencies into adjacent contributor b
 does not fan back out through unrelated siblings. These are presentation transforms over the
 validated snapshot; they do not add or change project relationships.
 
-All three views color edges by relationship semantics and retain direction with visible SVG endpoint
+Logic is available only when the focused node owns a stored `LogicProjection`. The browser
+retrieves that projection through a bounded, exact-owner endpoint. Entry, condition, action,
+control, merge, return, raise, and exit nodes remain outside primary graph search and traversal.
+Logic edges retain their declared `TRUE`, `FALSE`, `NEXT`, `CASE`, `LOOP`, `EXCEPTION`, `RETURN`,
+`RAISE`, `BREAK`, and `CONTINUE` labels. Hiding a logic node creates a visible omitted-path bridge
+between retained predecessors and successors instead of pruning valid downstream control flow.
+
+Nodes, Flow, and Web color edges by relationship semantics and retain direction with visible SVG endpoint
 symbols. Line patterns provide a non-color cue. A static canvas key shows the exact symbol, color,
 label, and visible count for each displayed relation, including a deterministic fallback for
-project-defined relations. Nodes, Flow, and Web use the same map.
+project-defined relations. Logic uses a separate fixed control-flow map.
 
 The browser derives node presentation roles only from the returned bounded graph. The current root
 is the focus. In Nodes, nodes reachable through outgoing edges are shown as outgoing paths; the
@@ -221,4 +228,5 @@ must also implement `load_projection()` so a clean rebuild and equivalence check
 
 Logic projections are not primary graph nodes. They remain source-scoped, function-owned,
 independently cached control-flow data so ordinary search, Nodes, Flow, and Web do not become
-statement graphs.
+statement graphs. Index schema 2 stores them in dedicated owner, node, and edge tables. Reads are
+bounded to one exact function or method owner.

docs/INCREMENTAL_INDEXING.md

@@ -131,8 +131,10 @@ raises. Logic edges retain relation, display label, and deterministic ordinal. A
 logic empty until they implement a language analyzer.
 
 This boundary prevents thousands of boolean expressions and basic blocks from polluting Nodes,
-Flow, Web, ordinary search, or architectural traversal. A future Logic view can request one
-function-scoped projection on demand.
+Flow, Web, ordinary search, or architectural traversal. The Logic tab and `docforge_get_logic`
+request one function-scoped projection on demand. The built-in Python analyzer covers conditions,
+short-circuit booleans, loops, `match`, exception paths, returns, and raises. It reports possible
+static paths; it does not claim runtime branch outcomes.
 
 ## Full rebuilds
 

docs/MCP_CONTRACT.md

@@ -15,6 +15,7 @@ canonical applier implementation.
 - `docforge_project_info`
 - `docforge_get_contract`
 - `docforge_get_node`
+- `docforge_get_logic`
 - `docforge_search`
 - `docforge_filter_nodes`
 - `docforge_backlinks`
@@ -85,14 +86,16 @@ only through the explicit local CLI integration command.
 
 ## Visualization boundary
 
-`docforge_visualize` starts the fixed built-in `graph-browser@15` template against the currently
+`docforge_visualize` starts the fixed built-in `graph-browser@16` template against the currently
 validated derived index. It may focus one stable node, run one bounded lexical query, or open the
 project overview. The tool returns a loopback URL and exact snapshot identity.
 
 The tool cannot select a project, database, template, host, port, filesystem path, or SQL
 expression. Its HTTP surface is token-bound, read-only, same-origin, and limited to overview,
 search, exact family/authority/status/tag filtering, node-neighborhood JSON, semantic Flow,
-convergence Web, and a bounded project-confined source read for one indexed node. The browser
+convergence Web, lazy function-scoped Logic, and a bounded project-confined source read for one
+indexed node. `docforge_get_logic` and the browser Logic endpoint accept one exact owner node ID and
+return only that bounded stored projection. The browser
 exposes an exact validated index snapshot. It rejects index
 replacement or alteration and requires another MCP invocation to refresh.
 Viewport interaction is entirely client-side: fitted neighborhood framing, wheel zoom, left-button
@@ -113,7 +116,10 @@ tooltips and inspectors. Flow presents semantic ancestry with relation-aware dir
 Web follows bounded structural, dependency, execution, evidence, and contextual contributors into
 the focus. Direct focus-owned members and execution dependencies become adjacent contributor
 branches without expanding unrelated siblings. The relationship key is regenerated from each
-visible view. The browser runs in a project-bound worker owned by
+visible view. Logic displays possible static control paths for a focused function or method without
+adding its statement-level nodes to primary search or architectural traversal. Hiding a Logic step
+bridges its retained predecessors and successors with an explicit omitted path. The browser runs in
+a project-bound worker owned by
 the separately supervised per-user viewer manager. Standard-input transaction completion and MCP
 host exit do not close the listener. Repeated visualization requests reuse the current worker while
 its exact snapshot remains valid. `docforge_visualization_status` reports lifecycle state, and

docs/USER_MANUAL.md

@@ -296,6 +296,30 @@ Adjacent traversal is deliberately bounded. After DocForge includes a direct mem
 dependency owned by the focus, it continues toward that branch rather than fanning back out
 through unrelated siblings. Depth and edge limits provide a second guard against an unbounded web.
 
+### Logic: possible control paths
+
+**Logic** answers: “What decisions and actions can occur inside this function or method?”
+
+Logic appears when the focused node owns a function-scoped `LogicProjection`. It loads that
+projection on demand instead of adding statements and conditions to the primary architecture
+graph. The view presents:
+
+- **Entry** and **Exit** terminals.
+- **Decision** cards for `if`, `elif`, compound booleans, loop conditions, `match` cases, and
+  assertions.
+- **Action** cards for executable statement blocks and calls.
+- **Control** cards for loops, `break`, and `continue`.
+- **Merge** cards where alternate paths converge.
+- **Terminal** cards for returns and raised exceptions.
+
+Edges use explicit labels and independent colors for `TRUE`, `FALSE`, `NEXT`, `CASE`, `LOOP`,
+`EXCEPTION`, `RETURN`, `RAISE`, `BREAK`, and `CONTINUE`. Long predicates wrap on the card. The full
+expression and source anchor remain available through inspection and source navigation.
+
+Logic is static analysis. It shows paths the indexed source permits, not the branch that ran for a
+particular request or the runtime value of a boolean. Dynamic dispatch, reflection, generated
+behavior, and values returned by other processes may require runtime tracing to resolve.
+
 ### Reading graph cards
 
 The canvas presents nodes as compact semantic cards rather than anonymous circles:
@@ -332,6 +356,9 @@ index, or future graph queries. The focus cannot be hidden; focus another node f
 - In **Nodes**, hiding removes only the selected node and its incident edges.
 - In **Flow** and **Web**, hiding removes the selected node, then prunes every upstream ancestor
   whose only remaining route to the focus passed through it.
+- In **Logic**, hiding removes the selected control-flow step and inserts an `omitted` bridge
+  between its visible predecessors and successors. This preserves the readable path without
+  pretending the hidden code disappeared from the indexed source.
 - Descendant nodes between the hidden node and the focus remain visible.
 - Ancestors with another valid path to the focus remain visible through that alternate path.
 - The status line reports how many nodes were hidden or isolated.
@@ -452,6 +479,7 @@ Example MCP client configuration:
 - `docforge_project_info`
 - `docforge_get_contract`
 - `docforge_get_node`
+- `docforge_get_logic`
 - `docforge_search`
 - `docforge_filter_nodes`
 - `docforge_backlinks`
@@ -523,8 +551,9 @@ canonical sources first. Incremental compilation then notices those changed sour
 it never treats an unapplied proposal as canonical.
 
 Function-scoped `LogicProjection` data is cached alongside its owning source but remains separate
-from the primary Nodes, Flow, and Web graph. This is the storage boundary for a future boolean and
-control-flow view without adding every condition and basic block to ordinary graph traversal.
+from the primary Nodes, Flow, and Web graph. The Logic tab and `docforge_get_logic` load one
+function or method on demand without adding every condition and basic block to ordinary graph
+traversal.
 
 See [Incremental Adapter Indexing](INCREMENTAL_INDEXING.md) for the complete contract, cache
 invalidation rules, manual-application lifecycle, and lazy Logic boundary.
@@ -606,7 +635,7 @@ ambiguous adapter evidence.
 ### Full inspector content does not fit
 
 DocForge 1.0 uses a fixed header and footer with a scrollable inspector body. If an older page is
-still open, stop and reopen the visualization so it loads the current `graph-browser@15` template.
+still open, stop and reopen the visualization so it loads the current `graph-browser@16` template.
 
 ### Render output is stale