feat(cli): make EQL reinstall dependency-safe

Author: tobyhede

.changeset/safe-eql-reinstall.md

@@ -0,0 +1,17 @@
+---
+"stash": patch
+---
+
+Preserve encrypted data and reconstruct functional indexes when reinstalling EQL v3, while refusing unsupported external dependencies before mutation.
+
+`stash eql install` and `stash eql upgrade` now capture dependent functional
+indexes before replacing the disposable EQL schemas, then restore and verify
+their definitions, clustering, replica-identity role, comments, ownership,
+explicit statistics targets, and health in the same transaction. A
+reconstruction failure rolls the replacement back.
+Unsupported dependencies—including views, policies, constraints, and
+partitioned indexes—are named and refused before mutation.
+
+Reinstall remains a maintenance-window operation: its advisory lock serializes
+`stash` lifecycle commands, not unrelated database DDL. Generated EQL migrations
+contain the raw bundle and do not include these reinstall protections.

.github/workflows/tests.yml

@@ -333,8 +333,10 @@ jobs:
       # (`installer/__tests__/verify.live.test.ts`) would run in no CI
       # workflow at all: a routine `@cipherstash/eql` bump could then make
       # every `stash eql install` fail with phantom damage, on green CI.
-      # These suites need Postgres only, no CipherStash credentials; the
-      # verify suite installs EQL v3 into its own schemas, which coexists
+      # Most suites need Postgres only. The encrypted-index upgrade suite also
+      # loads this job's CipherStash credentials from packages/stack/.env and
+      # uses the binding built above to create genuine ciphertext. The verify
+      # suite installs EQL v3 into its own schemas, which coexists
       # with the image's pre-installed EQL v2 that the stack tests use.
       # They share that one database, so the CLI vitest config runs them
       # serially (the `live` project sets `fileParallelism: false` —

AGENTS.md

@@ -84,10 +84,6 @@ If these variables are missing, tests that require live encryption will fail or
 - `packages/bench`: Performance / index-engagement benchmarks (private, not published)
 - `packages/protect-ffi`: Native FFI bindings to the CipherStash Client SDK (`@cipherstash/protect-ffi`) — the Rust core that `packages/stack` encrypts and decrypts through, absorbed from `cipherstash/protectjs-ffi`. Contains a **nested Cargo workspace** (`crates/`) and six per-platform binary packages under `platforms/*`, each published as `@cipherstash/protect-ffi-<platform>` and linked here via `workspace:*`. Also holds the repo's live FFI integration suite at `integration-tests/` — a private workspace member (`@cipherstash/ffi-integration-tests`) enrolled by its own literal entry in `pnpm-workspace.yaml`, needing Docker and credentials, and deliberately carrying **no `test` script** so `pnpm test` cannot reach it. See the "Working on protect-ffi" notes below before touching it — its default `test` and `build` are deliberately Rust-free.
 - `packages/eql`: The Encrypt Query Language subtree — the SQL bundle that stores and queries encrypted payloads — absorbed from `cipherstash/encrypt-query-language`. **The directory is the subtree root, not the package.** It was imported at a *verbatim prefix* so its repo-root-relative paths (mise tasks, `Doxyfile`, `sync-generated.mjs`) keep resolving, which puts the npm package `@cipherstash/eql` two levels down at `packages/eql/packages/eql` — the same shape as `packages/protect-ffi/platforms/*`, and enrolled the same way, by an explicit `packages/eql/packages/*` glob in `pnpm-workspace.yaml`. The subtree root deliberately carries no `package.json`. Also contains a **nested Cargo workspace** at `packages/eql/crates/` (`eql-bindings`, published in lockstep with the npm package, plus `eql-domains` / `eql-codegen` / `eql-tests-macros`, which are not), a SQLx test crate at `packages/eql/tests/sqlx`, an ~900-line `mise.toml` task surface, its own `AGENTS.md`, and `docs/`. See the "Working on EQL" notes below before touching it.
-  **Repository ownership:** EQL now lives in `cipherstash/stack`. File and update
-  EQL issues in this repository, never in the historical
-  `cipherstash/encrypt-query-language` repository. Old upstream issue and PR
-  links are provenance only.
 - `e2e/*`: Cross-package end-to-end tests (package managers, supply chain, Prisma example README)
 - `examples/*`: Working apps (basic, prisma, supabase-worker)
 - `docs/plans/*`: Internal design plans. User-facing documentation lives at https://cipherstash.com/docs (not in this repo).

CLAUDE.md

@@ -6,22 +6,6 @@ one source of truth.
 
 @AGENTS.md
 
-## Agent skills
-
-### Issue tracker
-
-Issues are tracked in GitHub Issues for `cipherstash/stack`. See
-`docs/agents/issue-tracker.md`.
-
-### Triage labels
-
-Use the five default triage labels. See `docs/agents/triage-labels.md`.
-
-### Domain docs
-
-Use a multi-context layout rooted at `CONTEXT-MAP.md`, with package-specific
-`CONTEXT.md` files added as needed. See `docs/agents/domain.md`.
-
 ## Before you finish
 
 Two rules from `AGENTS.md` are the ones most often missed. They are repeated here

CONTEXT-MAP.md

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.3/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.9/schema.json",
   "files": {
     "includes": [
       "**",

biome.json

@@ -1,9 +1,8 @@
 # EQL safe reinstall — durable data and reconstructed indexes
 
-Status: proposed
+Status: implemented
 Date: 2026-08-31
 Issues: cipherstash/stack#959, cipherstash/stack#918
-ADR: `docs/adr/0001-eql-data-survives-disposable-schema-reinstall.md`
 
 ## 1. Goal
 
@@ -30,8 +29,8 @@ mechanically stop the operation before the first destructive statement.
 
 ### Reconstructable
 
-- Functional indexes whose complete definitions can be obtained with
-  `pg_get_indexdef()`.
+- Standalone functional indexes whose definitions and supported catalog state
+  can be captured and restored.
 
 ### Fail-closed
 
@@ -61,22 +60,22 @@ lock serializes cooperating EQL lifecycle commands; it cannot serialize
 arbitrary DDL issued by unrelated PostgreSQL sessions without superuser-only
 event triggers. Application migrations must not run concurrently.
 
-1. Acquire an advisory lock preventing concurrent EQL lifecycle operations.
+1. Begin one transaction and acquire the transaction-scoped advisory lock that
+   serializes EQL lifecycle operations.
 2. Discover every customer-owned object with a dependency path to
    `eql_v3` or `eql_v3_internal`.
 3. Partition dependencies into reconstructable functional indexes and
    fail-closed objects.
 4. If any fail-closed or unknown dependency exists, print an inventory and exit
    before executing installer SQL.
-5. Capture each index's identity and `pg_get_indexdef()` output, including
-   schema-qualified table and index names.
-6. Begin one transaction, execute the shipped installer, and recreate captured
-   indexes before commit. Use the original definition by default; any
-   concurrent-rebuild mode must account explicitly for PostgreSQL's transaction
-   restrictions.
+5. Capture each index's identity, `pg_get_indexdef()` output, validity/readiness,
+   clustering, replica-identity role, and comment.
+6. Execute the shipped installer, recreate each captured index, and restore its
+   clustering, replica-identity role, and comment before commit.
 7. `ANALYZE` affected tables.
-8. Verify every captured index exists, is valid and ready, and still has the
-   exact server-rendered definition captured before replacement. Query-level
+8. Verify every captured index exists; its definition, clustering,
+   replica-identity role, and comment match; and its validity/readiness have not
+   regressed. Query-level
    engagement remains the responsibility of `stash eql validate`, which has
    the application schema needed to construct representative predicates.
 9. Commit only after verification, then release the advisory lock.
@@ -97,9 +96,8 @@ The classifier is an allowlist: only ordinary functional indexes with a complete
 server-rendered definition are automatically reconstructable. Every unrecognised
 class is fail-closed.
 
-Uniqueness, predicates, included columns, tablespaces,
-storage parameters, quoting, and non-`public` application schemas require test
-coverage before their corresponding index form enters the allowlist.
+Each supported index form and catalog property requires regression coverage.
+Partitioned index attachment trees remain fail-closed.
 
 ## 6. Acceptance criteria