docs(cache): amend ADR 0007 — row filtering adopted, column projection dropped - #1050
Open
AnthonyMDev wants to merge 13 commits into
Open
docs(cache): amend ADR 0007 — row filtering adopted, column projection dropped#1050AnthonyMDev wants to merge 13 commits into
AnthonyMDev wants to merge 13 commits into
Conversation
…n dropped Records the 2026-07-13 amendment: - Alternative B (row filtering with wide column projection) is the accepted read design; what PR-009g shipped is the intended shape, not a transition state. Column projection is dropped with the row-oriented-storage rationale (WITHOUT ROWID clustered rows; NULL columns cost ~1 header byte; narrowing saves no IO and fragments statement shapes), and it would have been incorrect against the shipped encoding regardless (null/custom-scalar/enum/integral-float column routing). - Position predicates are dropped: zero effect on well-formed data; declared-vs-stored shape mismatch stays a caller-visible JSONDecodingError.wrongType matching 2.x, by choice. - Principle 7 (custom-scalar column declaration) withdrawn; no codegen change needed. - Alternative F's rationale corrected: the __typename CTE did NOT land in PR-009g. It is deferred behind the new Tier 2 loadFields perf scenarios (added to the perf plan, including the inline-fragment over-fetch scenario that gates both the CTE and PR-009g-bis) and would arrive as an additive requiredTypename property. - Principle 6 / PR-009f row corrected to describe the shipped CacheDependentKey design. - Implementation sequence gains the PR-009g-ii slim row (#1049). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
✅ Docs preview readyThe preview is ready to be viewed. View the preview File Changes 0 new, 4 changed, 0 removedBuild ID: e5e75ea82c0524696ce6df2f URL: https://www.apollographql.com/docs/deploy-preview/e5e75ea82c0524696ce6df2f ✅ AI Style Review — No Changes DetectedNo MDX files were changed in this pull request. Review Log: View detailed log
|
… parsing Adds an INV-001 slot to §8: replacing JSONSerialization behind JSONSerializationFormat.deserialize is the Linux-portability enabler for the response path and would eliminate per-scalar NSNumber boxing, retiring SQLiteFieldEncoding's bridged-number classification. Wide blast radius (runtime type of every JSONValue), so it's tracked as a go/no-go investigation gated before the 3.0 final tag rather than slipped into Phase 1A. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…gates delete-then-write in writeFieldOrList is a correctness-over-throughput choice (~2N B-tree mutations per overwrite vs ~N for upsert + range-prune). Revisit after PR-011's Tier 2/3 write measurements; if kept, remove upsertRow's dead ON CONFLICT clause (the preceding delete makes conflicts impossible). Also pins a PR-009h design requirement: the field-level diff computed by mergeRecords must survive to the row layer — insertOrUpdate should receive partial Records of changed fields only, coordinated with the writtenAt-refresh persistence fix so TTL timestamp advances persist. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Prepared-statement caching for ApolloSQLiteDatabase's row-per-element statements, landing before PR-011 so the perf gates measure the cached shape. Consolidating the three cascade-CTE walks rides along, per review. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Actor + custom serial executor (UnownedJob recipe, iOS-15-compatible; SwiftNIO precedent) replaces the DispatchQueue + reentrancy token and moves blocking SQLite IO off the shared cooperative pool. Gated on the PR-009h / API-freeze checkpoint because the public SQLiteDatabase protocol becomes async throws. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Resolves the public-surface question the 2026-07-13 amendment deferred: the final 3.0 protocols expose only loadFields. PR-009h removes loadRecords, deletes the delegating default, graduates loadFields + FieldProjection to public, and gives InMemoryNormalizedCache a native implementation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4 tasks
…-iii) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ation rejection Records two 2026-07-28 review outcomes: PR-009g-bis's gate should weigh correctness-by-construction (eliminating the two-pass agreement obligation) alongside the perf measurement; and denormalizing child typenames onto CacheReferences was considered and rejected because path-keyed records can change runtime type, making pointer-copied typenames stale — the record's own __typename row plus the read-time SQL filter remains the design. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…d cache hits Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…yped @fieldPolicy docs Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ache-hit fetch signal Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… as pending Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ache hits Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Goal
Amend ADR 0007 so the documented design matches the shipped PR-009 stack and the decisions settled in review: row filtering is the accepted read design, column projection and position predicates are dropped (with rationale), and the
__typenameSQL filter is deferred behind named perf scenarios.Design doc reference
loadFieldsscenarios (projected load, projected batch load, projected list load, inline-fragment over-fetch). The over-fetch scenario is the explicit decision gate for the deferred__typenamefilter and PR-009g-bis.Position in execution plan
ADR amendment (docs PR against
cache-rewrite/phase-1-plan, per the ADR-PR merge cadence). Companion to code PR #1049 (PR-009g-ii).Stacks on
cache-rewrite/phase-1-planFollowups in this stack
FieldProjectionto(cacheKey, fieldName)(top of the code stack)SQLiteNormalizedCacheswitches to field-aware path + drop-and-rebuild migrationFiles changed
apollo-ios/Design/adr/0007-selection-aware-cache-reads.mdapollo-ios/Design/cache-rewrite-phase1-perf.mdTests added
None (docs).
Acceptance criteria
__typenameCTE "landed in PR-009g"wrongType(2.x-matching)__typenamefilter and PR-009g-bis share a named, runnable measurement gate in the perf planCacheDependentKeydesignVerification
apollo-ios/Design/.Notes for reviewer
The one decision this amendment deliberately does not make: the final disposition of
loadRecords(forKeys:)and the@_spi(Execution)gates onloadFields/FieldProjection/selectFields. The Decision section now carries an explicit pointer noting that's resolved at PR-009h / API freeze. Everything else in the amendment reflects decisions already settled in review discussion.🤖 Generated with Claude Code