vein: chat builder gets graph_query, rollback, run control, and validate_workflow

[Evanfeenstra]

What

Four additions to the AI builder's toolbelt:

1. graph_query — read-only raw Cypher against the vein graph, so the builder can verify what a workflow's graph/* steps actually wrote (counts by type, exact properties, edge fan-out) or inspect graph-backed workspace state.
2. set_active_version(kind, name, version) — rollback for workflows and custom steps. edit_step/edit_workflow already promised "prior versions kept for rollback"; this is the tool that delivers it instead of republishing old source as a fresh version.
3. cancel_run / pause_run / resume_run — control a run that is live in this process. run_workflow auto-detaches long runs, so the builder could launch but never abort.
4. validate_workflow(yaml) — static check before publishing, so a typo doesn't become a version.

graph_query design

• Read-only, enforced twice. A write-keyword pre-check (string literals / backticks / comments stripped, so n.data_set or 'reset' don't trip it) gives a clear error; the real guarantee is a READ-mode transaction, which the server rejects writes in. Matters more than usual since vein: graph workspace by default (VEIN_WORKSPACE_BACKEND=fs to opt out) #1632: the workspace itself lives in this graph.
• Capped. Streamed row cap (default 100, max 1000 — the remainder is never fetched), server-side tx timeout (15s), long strings truncated, embedding vectors collapsed to [vector: N numbers].
• Gated like bash/web_search. Offered only when AiDeps.graph is wired; server.ts passes the backend behind its graph-backed workspace via new VeinOptions.graph (type-only import — neo4j-driver stays lazy). Tool description carries the deployment namespace so the model filters on it.
• Chat tool, deliberately not a step. Raw Cypher in published YAML would bypass the schema validation + embeddings-on-write the graph/* steps exist for.

Run control wiring

AiDeps.controlRun is wired by createVein over the same controllers map the HTTP endpoints use; the cancel/pause routes were refactored to share one controlLiveRun helper with the chat tool (no behavior change — same status codes, same control-event markers).

validate_workflow

Pure module (src/validate.ts), fed the registry + workflow list by the tool.

Errors (would fail or hang at run time): YAML / unquoted-template problems; missing, duplicate, or unreferenceable step ids; unknown step types; depends on unknown ids (the runner would start the step early with an undefined input); self-deps and dependency cycles (the run hangs forever); template refs to unknown roots; token-level template syntax errors; config that fails the step's input schema (template-valued fields are skipped — they resolve at run time); when without depends; loop without until; foreach without items; malformed retry; subflow targets/versions that don't exist.

Warnings: unknown config fields; when without an if gate among its depends; template refs to steps that aren't upstream dependencies.

Publishing is gated on it. create_workflow / edit_workflow run the same check first; on errors they return { error, validation } and write nothing — the error is one readable paragraph ("Not published: … N validation errors (nothing was written; no version was created)", the path: message list, "fix these and call again — validate_workflow re-checks without publishing"). Warnings never block; they ride along on the success result. A YAML without name: still passes (the publish stamps it in).

Loop/foreach bodies are checked with $current/$index in scope, onError steps with $error. expr.ts gains exprRoots() (tokenizer-only root extraction; member names and lambda params excluded) and templateExprs(). The system prompt's step 4 is now "validate, fix errors, then create_workflow".

Tests

• src/graph/query.test.ts — pure guard/compaction + tool gating (always run); live cases against the throwaway Neo4j (params, row cap, default cap, pre-check rejection, server-side write rejection, syntax errors, empty-result columns).
• src/ai-integration.test.ts — workflow + step rollback round trips (history kept, bad version / missing name errors, publishing-disabled refusal); run-control tool gating and relay.
• src/validate.test.ts — exprRoots/templateExprs; a full well-formed workflow (if-gate, loop, foreach, subflow, onError) validates clean; each error/warning class has a case; ai-integration.test.ts covers the publish gate (refusal text, nothing written, warnings on success, edit leaves the version untouched).

Full npm test green (663); tsc --noEmit clean.

🤖 Generated with Claude Code