Skip to content
Canonical

DR-100: ast-dataflow warm path is a warm process, not a persisted cache

DR-100: ast-dataflow warm path is a warm process, not a persisted cache

Section titled “DR-100: ast-dataflow warm path is a warm process, not a persisted cache”

Context

Section titled “Context”

ast-dataflow’s PRODUCT invariants 19-22 assumed a “warm cache”, and the ROADMAP carried an LMDB facts-cache design (R-WP9/OQ-R3) for years of sessions. The id-375 research pass measured where cold-start time actually goes: 11 of 12 queries consume the live type-checked ts-morph AST, so a per-file extracted-facts cache would serve roughly one query while adding an invalidation surface.

Decision

Section titled “Decision”

The warm path is a long-lived process — a stdio MCP server holding the ts-morph Project — not a persisted index file. Per-file invalidation maps to refreshFromFileSystem() on mtime+size change; staleness is reported loud via a meta envelope field. The CLI remains the always-available cold path. Shape: a single dispatching ast_dataflow tool over a shared dispatch.ts consumed by both CLI and server (PRODUCT.md A2+A3, ratified 2026-07-27). Rider: registration in .mcp.json is deferred to the extraction phase — canonical installs the extracted tool and registers the MCP as an end user would, with an /mcp-builder best-practice audit of the server at that point.

Alternatives Considered

Section titled “Alternatives Considered”
  • LMDB per-file facts cache (R-WP9/OQ-R3 design): rejected by measurement — most queries need the live type checker, not extracted facts.
  • Shared daemon: rejected — a client-owned per-session subprocess keeps the always-works CLI contract (inv 21) without daemon lifecycle management.

Consequences

Section titled “Consequences”
  • R-WP9/OQ-R3 rows in the id-50 ROADMAP are stamped SUPERSEDED-id-375.
  • Warm-query latency: first call ~6 s (project load), subsequent ~100-200 ms.
  • The server stays unregistered until extraction; sessions use the CLI or start the server explicitly via bun run ast-dataflow-mcp.

Depth: specs/id-375-ast-dataflow-productionise/RESEARCH.md §6 and specs/id-50-ast-dataflow-tool/PRODUCT.md §Amendments (A2/A3); canonical commit aa494e49.