Finish lifting the per-kind node methods out of SceneDocument

[dovvnloading]

Problem

SceneDocument is where a node kind lives. Adding one means editing that
class, and it had grown to 2,591 lines holding methods for fifteen different
kinds side by side. PR #409 moved the two largest groups (code_review,
gitlink) into their own mixins and left the other thirteen behind.

A second problem sat underneath it. SceneNode.state is typed
NodeState | None against a field-less marker class, so every
node.state.<kind>_<field> access in those methods was unverifiable — which
is why [tool.mypy].files had only ever reached three modules inside
backend/domain/.

Change

Two commits, best read in order.

1. The relocation

42 members and 983 lines out of graph.py, into five mixins grouped by what
the kinds actually share rather than one module per kind:

module	mixin	kinds
nodes_agent_runs.py	AgentRunOps	web_research, artifact, code_sandbox — the three with a start/progress/complete/fail run lifecycle
nodes_planning.py	PlanningOps	plan, harness
nodes_conversational.py	ConversationalOps	chat, conversation
nodes_content.py	ContentOps	document, thinking, html, note
nodes_visual.py	VisualOps	chart, image

graph.py goes from 2,591 lines to 1,502, and holds no per-kind methods at
all. Nothing outside backend/domain/ changes: SceneDocument is composed
from mixins, so every existing caller keeps working untouched — the wire
payload, both persistence sides, the intent modules and the client never see
this.

Every one of the 42 moved members was verified four ways: AST-identical to
its pre-move version (an ast.unparse round-trip against
git show HEAD:backend/domain/graph.py), absent from SceneDocument's own
body afterwards, reachable on SceneDocument, and defined exactly once
across the whole MRO. Methods are regrouped by kind inside each new module
instead of keeping the order successive increments happened to append them
in; nothing else changed.

SceneDocumentParts gains adopt_pending_system_prompt, which
add_chat_node calls and which stays on SceneDocument. Its add_chat_node
declaration is tightened from a *args: Any, **kwargs: Any hedge to the real
signature — the hedge was fine while the body lived in SceneDocument
itself, but now that ConversationalOps defines it, an inexact declaration
in a base class is an incompatible-override error rather than a harmless
fiction.

2. The narrowing

Those five modules reported 92 mypy errors, all of the union-attr shape
above, and all 92 sat in exactly 17 methods — each opening with the same
hand-written preamble that require_node/optional_node
(backend/domain/node_access.py, #410) already replaces. Converted; the five
modules now check clean.

Nine were a straight swap: they already checked the kind and raised the same
two messages require_node raises.

The other eight gained a kind check they did not have, and that is a
behaviour change. The completion and failure paths for web_research,
artifact and code_sandbox looked their node up without checking its kind, on
the reasoning — written into two of the docstrings — that the id had already
been validated by the matching start_* call earlier in the same request.
That is true, and still true: the check is redundant on every live path.

It is also why the gap was invisible. Node states are plain, non-slotted
dataclasses, so node.state.research_stage = "completed" against a chat node
does not fail — it grafts a phantom attribute onto ChatState and returns
happily.

backend/tests/test_wrong_kind_node_guards.py pins the new contract for all
eight, plus complete_gitlink_run and complete_gitlink_apply, which gained
the same check in #409 with nothing asserting it. Each case is checked three
ways: the wrong-kind call raises SceneError (or, for the fail_* methods,
returns None, matching their documented silence when the node has gone),
and the wrong-kind node's state is left byte-identical.

[tool.mypy].files widens from 3 backend/domain/ modules to 13 of 18. The
five left out are graph.py and the four cross-cutting mixins
(groups/branches/commands/layout), which hold 124 errors of the same shape —
they read per-kind state off nodes they look up generically, so
require_node has no kind to narrow to. Recorded in the config comment as
the next piece of work rather than waved through.

Notes

• One error message changed: set_html_splitter_state said "node is not an html node" and now says "a html node", the wording every other kind
  produces. Nothing in the repo or the client reads it.
• Lift the two largest per-kind method groups out of SceneDocument #409 left two section-header comments in graph.py describing methods it
  had just moved away, plus 21 stray blank lines where they used to sit. The
  headers carried real information about those kinds' import posture, so that
  text moves into the nodes_gitlink.py and nodes_code_review.py module
  docstrings instead of being dropped.

Test plan

• Full suite: 3,244 passed, 19 skipped. Two unrelated subprocess-timing
  tests (test_mcp_client stdin-drain, test_execution_guard
  grandchild-kill) failed under load in that run and pass on their own;
  neither imports backend.domain.
• ruff check . clean. mypy clean across 42 source files.
• The new guard test was verified to fail when a guard is removed and pass
  when it is restored, so it is not a vacuous gate.
• Existing coverage is the real regression check here: 497 tests across
  test_canvas.py, test_agents.py and test_review_lens_backend.py
  exercise these methods and were untouched.

🤖 Generated with Claude Code