docs(cache): amend ADR 0007 implementation sequence (d-iii, d-iv, 009g design, 009g-bis)

[AnthonyMDev]

Records the architectural decisions surfaced during review of PR-009d-i (#1012) and PR-009d-ii (#1013) on sub-phase 1A.5's implementation sequence. Docs-only — no code changes.

New entries in the implementation sequence table

• PR-009d-iii — FieldExecutionInfo memoizes its CacheFieldKey, mirroring the existing _cacheKeyForField cache pattern. Small follow-up to PR-009d-ii (~30 LoC). Resolver-side cache field key resolution becomes O(1) per info.

• PR-009d-iv — extract a shared SelectionWalker that deduplicates the Selection-case dispatch logic between DefaultFieldSelectionCollector (resolve path) and FieldProjectionCollector (projection path). Parameterized by per-field action + InlineFragmentPolicy + DeferredFragmentPolicy. Lands before PR-009f so the dependency tracker uses the unified helper.

• PR-009g design choice — the SQL-level type-conditional projection uses a single-query CTE / correlated subquery on __typename to filter inline-fragment fields by runtime type. No two-pass round-trip.

• PR-009g-bis (NEW, optional) — cross-phase FieldExecutionInfo sharing. FieldProjectionCollector.collect(...) emits (Set<FieldProjection>, FieldSelectionGrouping); the executor's groupFields accepts the precomputed grouping for cache-path execution sources. Combined with PR-009d-iii's info memo, this eliminates the projection-time / resolve-time recompute of cacheFieldKey entirely. Gated on profiling after PR-009g.

New 'Alternatives considered' entries

• F. Two-pass cache read to resolve runtime type before projection. Rejected — doubles round-trips; the single-query CTE design in PR-009g achieves the same precision without the cost.

• G. Cross-phase FieldExecutionInfo sharing as a Phase 1A foundation. Deferred (not rejected) — captured as the optional PR-009g-bis, gated on profiling. The collector-then-resolver dataflow is design-compatible; landing the foundation now doesn't preclude the optimization later.

Calendar estimate

Updated from ~17 PRs to ~19 PRs (~20 if PR-009g-bis lands), ~5–7 weeks for Phase 1A.

Why these decisions weren't in the original ADR

The d-i/d-ii split was anticipated in the original ADR's Risk and Rollback section. The d-iii (info memo) and d-iv (walker extraction) cleanups came out of PR-009d-ii's review — the cache field key resolution was duplicated between the executor's resolveCacheKey and the new collector's cacheFieldNames, which prompted the refactor into a shared Selection.Field.cacheFieldKey(...) helper, which in turn made the memoization opportunity visible. The walker extraction surfaced when reviewing whether FieldProjectionCollector should conform to FieldSelectionCollector — the protocol-level unification was forced, but the Selection-case walk logic is genuinely duplicated and benefits from a shared helper.

The PR-009g design was always TBD in the original ADR; we now have a concrete commitment (single-query CTE) and a documented rejection of the two-pass alternative.

The PR-009g-bis option emerged from the same review thread — the cross-phase sharing is a real optimization but its payoff depends on policy-resolution cost on realistic workloads, which is best evaluated after PR-009g lands and the IO over-fetch is bounded.

References

• ADR 0007 — Selection-set-aware cache reads (this amendment)
• PR refactor(executor): introduce FieldProjectionCollector (PR-009d-i) #1012 — PR-009d-i (FieldProjectionCollector)
• PR refactor(executor): CacheDataExecutionSource adopts upfront projection (PR-009d-ii) #1013 — PR-009d-ii (CacheDataExecutionSource adopts upfront projection)

🤖 Generated with Claude Code