Complete the tested Protect-to-Stack v3 DynamoDB guide #1604

Parent

#1540

What to build

Finish the DynamoDB procedure of the v2-to-v3 guide, using the existing compatibility and cross-store coverage in PR #1519. A reader can prepare a Protect application, upgrade it to a pinned Stack v3 API release, verify existing data and new writes, and understand the deployment and rollback limitations. Follow the priority amendment in ADR PR #1575; keep the authoritative specification there.

Acceptance criteria

• The guide distinguishes EQL generations from package majors and identifies the tested Protect and Stack versions.
• An executable before/after example follows the guide using npm and preserves supported legacy item ciphertext and equality terms.
• Existing reads and supported equality lookups, fresh writes, downcase normalization, boolean lookup replacement, stale-HMAC removal and bigint serialization are covered by passing live tests.
• Legacy JSON conversion and unsupported types, grouped fields, dates, lock contexts and query capabilities are explicitly classified; no universal no-re-encryption claim is made.
• Preparation, verification, deployment and rollback limits are documented. Cross-store copying is optional and does not claim to migrate an existing EQL v2 Postgres database.
• Each compatibility claim has an accurate citation, the citation gate passes, and the existing live compatibility suites pass in CI. DynamoDB Local/in-memory evidence is distinguished from AWS operational guarantees.
• The guide links to the Postgres procedure when Deliver a tested Protect/EQL v2 to Stack/EQL v3 Postgres procedure #1603 lands; shared preparation remains consistent.

Blocked by

None — can start on PR #1519's branch. PR #1519 must be integrated before this work merges. No harness automation or v4 dependency.

Delivery status — 2026-11-12

The source guide is #1620 at a6d33c9e8f7acc65158553bbce5b7b6ff62165a2, SHA-256 6e730d48fdba975c55273f3c9d58f27c21928babe8607c862a6b0eca996bc242. It now generates the complete standalone PostgreSQL script from the executable module, verifies Protect source plaintexts independently against Stack, batches SDK operations, and resolves catalog identities without physical-column/search-path assumptions. The explicit credentials snippet and immutable links are corrected.

Current live E2E passed: 14 guide tests on each of PostgreSQL 17 and 18, including the actual pasted script, dropped-column fixture, both restricted search paths and missing-primary-key refusal. The combined PG17 suite passed 27 tests. Local verification passed 74 focused tests, strict example/snippet compilation against published packages, typechecking and the lint gate. The previous PG17 fixture failure reproduced once; the test-only follow-up explicitly targets public and checks setup before migration.

Customer documentation is synchronized in cipherstash/docs#118 at signed 5259b44995b09ab7d3cac62003e77d3b68c58c00, pinned to the byte-identical guide at e7d6a02d3. Source equivalence, types, content, links, scoped lint, production build and docs CI pass. Two pre-existing full-docs-lint formatting errors remain. Nothing is merged or deployed.

Keep this issue open until source-guide integration and docs publication are complete. Customer schema/query inventory, AWS/PostgreSQL staging and operational cutover/recovery rehearsal remain handoff gates. Previous model runs used guide hash 46106cc0… and do not validate this changed guide; full evidence and remaining harness acceptance gaps are tracked in #1540.