Skip to main content

Module preflight

sqlite_graphrag::spawn

Module preflight 

Source
Expand description

Pre-flight validation layer for LLM subprocess spawners (v1.0.87, ADR-0045).

GAP-META-005: closes the architectural gap between build_argv and cmd.spawn() in the four real subprocess spawn sites (claude_runner.rs:255, codex_spawn.rs:273, ingest_claude.rs:297, extract/llm_embedding.rs:671). Before this module, the 4-stage pipeline was:

1. build_argv(mode, prompt, body)  -> Vec<OsString>
2. apply_env_whitelist(cmd)         -> void (helper v1.0.83, ADR-0041)
3. Command::spawn()                 -> io::Result<Child>
4. child.wait_with_output()         -> io::Result<Output>

Stage 3 discovered failures AFTER the kernel fork and AFTER Claude Code started executing, wasting tokens, locking job-singleton, and producing opaque diagnostics. This module inserts a gate between stages 2 and 3 that catches the 5 bug-symptom classes documented in gaps.md BEFORE the fork:

  • Bug 1 — ingest --extraction-backend llm extracts 0 entities silently
  • Bug 2 — --mcp-config '{}' rejected by Claude Code 2.1.177
  • Bug 3 — argv > ARG_MAX post-fork E2BIG
  • Bug 4 — output parser truncates at 65536 chars
  • Bug 5 — .mcp.json walk-up fails Zod validation

Pattern: sibling of env_whitelist.rs (v1.0.83, ADR-0041). Same design philosophy (helper consumed by all 4 spawn sites, no caller-local reimplementation, opt-out via env var for emergencies).

§Invariante imposta

sqlite-graphrag executa Claude Code e Codex CLI obrigatoriamente headless sem MCP. Pre-flight rejeita argv que carrega MCP servers explícitos antes do fork, fechando o caminho onde ~/.claude/settings.json ou walk-up de .mcp.json herdado poderia reintroduzir plugins contra a policy.

Structs§

PreFlightArgs
Arguments for the pre-flight validation gate.

Enums§

PreFlightError
Structured errors from the pre-flight gate. Each variant carries the data needed for an operator to diagnose without re-running.

Functions§

is_skipped
Skip pre-flight checks entirely. Emergency escape hatch — strongly discouraged. Operators accept the 5-bug-class risk by setting this.
preflight_check
Returns Ok(()) when all checks pass, or the first failing variant.
write_empty_mcp_config_tempfile
Writes an empty MCP config tempfile with {"mcpServers":{}} and returns the path. Callers should cmd.arg(path.as_os_str()) to substitute for the inline '{}' literal rejected by Claude Code 2.1.177.