docs(cache): rewrite §7.1, §7.2, §7.3 and amend §8 PR-009 per ADR 0006

[AnthonyMDev]

Summary

Propagates ADR 0006 — List storage: in-place row-per-element with position — into the engineering plan and execution plan.

Stacked on #1002. Targets the ADR PR's branch (cache-rewrite/adr-0006-list-storage). When #1002 merges into cache-rewrite/phase-1-plan, this PR rebases and retargets per execution plan §7's re-stack policy.

Engineering plan changes (cache-rewrite-phase1-plan.md)

§7.1 DDL — list_value TEXT removed; position INTEGER NOT NULL DEFAULT -1 added; PK extended to (cache_key, field_name, position). Brief preamble explains the row-per-element semantics and cites ADR 0006. Schema version bumped from 3 to 4.

§7.2 Operations — selectRecords orders by (cache_key, field_name, position); decoder branches on position to dispatch scalar (= -1) vs list-element (>= 0) rows. addOrUpdate produces one row per scalar field and N rows per list-typed field, with atomic list-element rewrite. deleteRecord covers the depth ≥ 2 cascading reachability walk for nested-list sub-records.

§7.3 Migration — trigger updated from < 3 to < 4. Adds a sentence noting that the trigger absorbs both 2.x upgrades and any local-dev databases on v3.

Execution plan changes (cache-rewrite-phase1-execution.md)

§8 Phase 1A table — split the DDL replacement and CRUD work into two PR slots that follow the existing sub-ID convention (PR-004a, PR-004b, PR-011a, PR-011b, PR-022a all extend a parent PR's theme with additional related work):

• PR-008b (new) — feat(sqlite): replace records DDL with position-keyed v4 schema per ADR 0006. Drops/recreates the records table with the extended PK; bumps schema_metadata version 3 → 4; updates the migration trigger to < 4. ~150 LoC. Base: PR-008.

• PR-009 (narrowed) — feat(sqlite): row-per-element CRUD against position-keyed schema. Position-aware encoder + decoder; nested-list synthetic sub-record recursion at depth ≥ 2; atomic list-element rewrite. No longer carries the schema version bump (lives in PR-008b). ~600 LoC, back under the §6 trigger 1 threshold. Base: PR-008b. Supersedes the original "JSON list_value CRUD" scope.

Phase 1A header bumped from (10 PRs) to (11 PRs). PR-010 and beyond unchanged (PR-010's Base stays PR-009).

One judgement call to confirm — schema version bumped 3 → 4

PR-008 (already merged) stamped v3 with the old JSON-list shape. ADR 0006 changes the records-table column shape, PK, and row semantics. Bumping to v4 gives any local-dev databases that ran the v3 shape on the plan branch a clean drop-and-rebuild on next launch (the §7.3 migration trigger catches < 4). Keeping v3 with redefined meaning was the alternative; I picked the bump for cleaner version-history discipline. v3 never tagged externally so no end-user installation is affected either way.

What stays the same

• Migration mechanic (drop-and-rebuild on first 3.0 launch) is unchanged.
• §7.4 performance gates are unchanged (the existing gates are scalar-path; list-heavy scenarios land in PR-011 / PR-011a as permanent coverage per ADR 0006).
• All Phase 1B, 1C, 1D plans are untouched.
• PR-010, PR-011, PR-011a, PR-011b, PR-012 entries unchanged.
• PR-008's row in §8 is left as-is (already merged; the "v3 stamped" tests-required reflects what PR-008 actually did at merge time; PR-008b's row carries the v3 → v4 bump narrative).

Revision history

• 282a1ee71 — initial split: §7.1/§7.2/§7.3 rewritten; §8 PR-009 collapsed both DDL + CRUD into a single amended row with ~700 LoC.
• edf4ec586 — split PR-009's amended scope into PR-008b (DDL) + narrowed PR-009 (CRUD), per the existing sub-ID convention. PR-009 LoC back to ~600, no longer crosses §6 trigger 1.

Out of scope

• The actual code changes for PR-008b and PR-009. Those land as the next implementation step after this docs PR and docs(cache): ADR 0006 — list storage strategy #1002 both merge.
• PR Phase 1 cache rewrite — long-lived design and execution plan #967 tracker update — to be done via gh api PATCH after this PR opens (adds the PR-008b row in Phase 1A and amends PR-009's row title; bumps the Phase 1A counter).

Test plan

• Docs-only PR — no build/test gates required (per execution plan §5).
• Reviewer confirms the v3 → v4 schema version bump is the preferred discipline (vs. redefining v3 in place).
• Reviewer confirms the PR-008b + PR-009 split is the right shape (vs. collapsing both into PR-009, or renaming the amended slot to PR-009b).
• Reviewer sanity-checks the §7.2 operations descriptions — especially the depth ≥ 2 cascading-reachability walk note on deleteRecord.
• PR Phase 1 cache rewrite — long-lived design and execution plan #967 tracker updated separately to add the PR-008b row, amend PR-009's title, and bump the Phase 1A counter (done via gh api PATCH after this PR is opened).

🤖 Generated with Claude Code

[apollo-librarian]

✅ Docs preview has no changes

The preview was not built because there were no changes.

Build ID: 8d877dcfae46028f1a68c4d4
Build Logs: View logs

---

✅ AI Style Review — No Changes Detected

No MDX files were changed in this pull request.

Review Log: View detailed log

This review is AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.