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 tested procedure and executable examples landed in #1519. Final source-guide corrections are in draft #1620 at 0ecabc3f62ee8a117c467981ce00d312e6cfc636: explicit in-memory evidence qualification, inline tested PostgreSQL dependency preflight, safe repeat-conversion refusal, explicit credentials and the regression guarding use of Stack after Protect is removed. Current-head CI passed 40 DynamoDB compatibility tests, 23 crossover/example tests and 10 PostgreSQL 18 tests.

Customer documentation is prepared in draft cipherstash/docs#118, signed commit 33e92186fa1d1f1376b07b9b1d62323452aab40f. It preserves the frozen procedures and snippets, pins example links to that source revision, and adds a customer staging/recovery checklist. Production build, typecheck, content validation, internal links/anchors, diagrams and 621 redirect checks passed. Full docs lint has two verified pre-existing formatting failures outside this change; scoped lint passes. No production publication is claimed.

A clean npm installation outside the monorepo verified the exact published package pins on Node 22.23.1/macOS arm64, native example imports, strict example TypeScript and Stack-only imports. This does not establish live AWS behavior or customer-specific compatibility.

Fresh guide-only runs on the existing Colima VM passed 24 DynamoDB and 15 PostgreSQL Oracle checks with empty friction logs against final guide hash 46106cc0a71dbeb757bcb0b3889c6fc5741bac201afe807ed8cde0a035d3d649. Complete broker evidence was independently audited; exact harness revision and evidence limits are recorded in #1540. These are one clean sample per store, not convergence or customer staging proof.

Keep this issue open until source-guide integration and docs publication are complete. #1620 requires an approving review. AWS staging, customer schema/query inventory and operational recovery rehearsal remain explicit handoff gates rather than claims implied by the in-memory compatibility suite.