ADR-0023: Explicit server EXPLAIN without query execution¶
Status: verified locally and in hosted run 38131881765 at aa8a052: 15 unit lifecycle/guard cases and four real-plan cases.
The feature strategy asks for real plan visibility, a query-shape fingerprint and deliberate PROFILE use. Add Database.ExplainCypherAsync as a small provider-native API using the existing context options, EF concurrency detector and native-operation guard. It returns the driver's IPlan, server planning timings and SHA-256 of the exact supplied statement text. Parameter values are excluded from that fingerprint; literals in raw statement text are not normalized away. This identity is diagnostic, not a new query cache or a guarantee that different parameters produce identical plans.
The prototype accepts bare MATCH/OPTIONAL/WITH/UNWIND/RETURN/CALL/CREATE/MERGE statements and prepends EXPLAIN itself. Leading comments and mode/dialect preambles reject before transport. It does not rewrite Cypher to insert modes, automatically run PROFILE, execute a plan, or infer LINQ closure parameters. Generated ToQueryString text is supported when the caller supplies its placeholders in driver/store representation. Automatic compiled-query parameter extraction is a potential later API, not a claim of this prototype.
Owned read-routed transactions are rolled back, with transaction/session cleanup attempted even on failures. Borrowed EF transactions remain caller-owned. The helper checks zero result rows, a non-profile plan and zero data/system update counters before accepting the result. Primary errors survive cleanup failures; cleanup failure after otherwise successful inspection is surfaced. Cancellation is cooperative between awaited driver operations, consistent with the driver surface and the existing native APIs.
Plans can include application literals in their arguments. Nothing is logged automatically. A configurable node cap rejects oversized/cyclic plan trees, but it applies after driver summary materialization and does not bound server planning work or argument byte sizes. Driver diagnostics configured by an application are outside this helper's privacy policy.
PROFILE remains an explicitly caller-authored native Cypher operation; it executes the statement, including writes. No boolean flag on the EXPLAIN helper can silently switch to PROFILE. Review inspection examples before opting into native profiling. Tests cover real read/write planning without mutation, caller transaction preservation, generated LINQ text with explicit store parameters, cancellation, protocol rejection and cleanup.