refactor(stack): EQL v3 types namespace on @cipherstash/stack/eql/v3

[tobyhede]

Refactors the EQL v3 authoring surface: the per-domain encrypted<Domain>Column factories become a single types namespace whose members mirror the underlying eql_v3.<name> domains, on the renamed @cipherstash/stack/eql/v3 subpath.

import { encryptedTable, types } from "@cipherstash/stack/eql/v3";

const events = encryptedTable("events", {
  actor:     types.TextEq("actor"),           // equality
  weight:    types.Int4Ord("weight"),         // order + range
  createdAt: types.Timestamptz("created_at"), // storage only
});

Before → after — the name maps 1:1 to the EQL v3 domain:

// before                                          // after
encryptedTextEqColumn("actor")                     types.TextEq("actor")          // eql_v3.text_eq
encryptedInt4OrdColumn("weight")                    types.Int4Ord("weight")        // eql_v3.int4_ord
encryptedTimestamptzColumn("created_at")            types.Timestamptz("created_at")// eql_v3.timestamptz
encryptedTextSearchColumn("email").freeTextSearch() types.TextSearch("email").freeTextSearch()

Per-domain plaintext inference and compile-time queryability are unchanged:

import { Encryption } from "@cipherstash/stack";
import type { InferPlaintext } from "@cipherstash/stack/eql/v3";

type Events = InferPlaintext<typeof events>;
// { actor: string; weight: number; createdAt: Date }

const client = await Encryption({ schemas: [events] });

await client.encryptQuery(30, { table: events, column: events.weight, queryType: "orderAndRange" });
await client.encryptQuery(new Date(), { table: events, column: events.createdAt });
//                                                            ^ type error: storage-only, not queryable

The @cipherstash/stack/v3 typed client re-exports types (in place of the standalone builders):

import { EncryptionV3, encryptedTable, types } from "@cipherstash/stack/v3";

const users = encryptedTable("users", { email: types.TextSearch("email") });
const client = await EncryptionV3({ schemas: [users] });

await client.encrypt("a@b.com", { table: users, column: users.email }); // ok
await client.encrypt(123,       { table: users, column: users.email }); // ✗ number ≠ string

types members

One member per generated EQL v3 domain (PascalCase of the eql_v3.<name>):

Int4 Int4Eq Int4OrdOre Int4Ord · Int2* · Date* · Timestamptz* · Numeric* · Text TextEq TextMatch TextOrdOre TextOrd TextSearch · Bool · Float4* Float8* (int8/bigint still omitted pending lossless FFI I/O). Each returns its concrete branded class, so per-column inference stays precise.

Scope

• Splits the 992-line schema/v3/index.ts into src/eql/v3/{columns,types,table,index}.ts.
• Renames the subpath schema/v3 → eql/v3 (exports, tsup entry, FTA gate, ./v3 re-export); the old subpath and the standalone factories are removed.
• Behaviour preserved: same classes, nominal typing, and build() output (text_search stays byte-identical).

Verified: schema/v3 no longer resolves (ERR_PACKAGE_PATH_NOT_EXPORTED) and factories are undefined on both subpaths; 101 v3 runtime + 50 type tests pass; FTA scores all 4 files (max 68.68 < 72). Stacked on #535.

[changeset-bot]

⚠️ No Changeset found

Latest commit: dcd0fe7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes changesets to release 6 packages

Name	Type
@cipherstash/stack	Minor
@cipherstash/bench	Patch
@cipherstash/prisma-next	Patch
@cipherstash/basic-example	Patch
@cipherstash/prisma-next-example	Patch
@cipherstash/e2e	Patch

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6c441b96-e254-4709-b648-7777a38ac6e4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/eql-v3-types-module

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[freshtonic]

I approve but I notice that timestamptz is back - I thought we finally reached a conclusion (that Claude's advice was incorrect)?

[coderdan]

Tres excellente!

[coderdan]

From test-gap-review:

Test-coverage review — eql/v3 authoring DSL

Verdict: coverage is strong; one small lopsided gap worth closing.

The bulk of this PR is a rename/refactor (schema/v3 → eql/v3, the encrypted*Column factories → the types.* namespace) whose behavior is pinned by the exhaustive type-driven V3_MATRIX: matrix.test.ts asserts builder/getName/getEqlType/getQueryCapabilities/isQueryable/build() for all 35 domains, matrix-live*.test.ts roundtrips every domain through live FFI + Postgres, and the genuinely-new logic (text-order domains carrying the hm/unique index) already has dedicated regression tests. New public Buildable* type exports are guarded by types-public-surface.test-d.ts. The table guards (duplicate DB-column name, duplicate table name, reserved-key collision incl. prototype members) are all tested.

Inline gap (1)

packages/stack/src/eql/v3/columns.ts:355 — base-class match-index clone in indexesForCapabilities() (used by eql_v3.text_match) has no cross-column mutable-state test, while the parallel EncryptedTextSearchColumn.build() override does. Classic lopsided-clone-path anti-pattern: a regression to a shared const default would be caught for text_search but slip through for text_match. Sketch mirrors the existing "built columns share no mutable state" test using types.TextMatch(...). Passes today; fails if the base path stops cloning.

Additional gaps (body only)

• freeTextSearch() called with no argument (opts === undefined) — untested branch; every test passes an explicit opts object.
• buildEncryptConfig() with zero tables — untested empty-input boundary. Low value.

No security issues noticed incidentally.

[freshtonic]

Multi-angle review of this PR (8 finder passes + adversarial verification of each candidate, checked against current main since the PR is already merged). The refactor itself is clean — every export of the old schema/v3 barrel survives the split except the intentionally-removed factories, no stale schema/v3 references remain in exports/tsup/CI, the subpath was never published so the rename breaks no consumer, and the types.* → class → domain-const mappings are all consistent. Findings below are ranked most-severe first; all are follow-up material rather than blockers.

Verified findings

1. __tests__/v3-matrix/matrix-live-pg.test.ts (proofKindFor) — text order domains silently lost their live ORE proof.
Switching the catalog to TEXT_ORD_IDX = { unique: …, ore: {} } reclassifies eql_v3.text_ord / text_ord_ore under proofKindFor's unique-first priority: both now run only the eq_term/hmac_256 proof and never the ord_term/ore_block_256 proof. A wrong-valued ob term for text order domains would pass the whole live matrix green (a missing ob still fails the domain CHECK on insert, but wrong values don't). The doc comment ("every *_ord/*_ord_ore domain (including the text ones) gets the equality-via-ORE proof") and the catalog.ts note about the ord proof selecting row A are now both false. Fix: teach the classifier a third eq+ord kind for text order domains (they carry both indexes) so they run both proofs.

2. .changeset/eql-v3-typed-schema.md + eql-v3-typed-client.md — pending changesets still promise bigint / int8 support the code intentionally omits.

NOTE: James has an open PR for supporting bigint

The changesets say encrypt/encryptQuery were widened to include "Date and bigint … so v3 date/timestamptz/int8 domains can be encrypted" and "int8 → bigint", but Plaintext = JsPlaintext | Date (src/types.ts) explicitly excludes bigint (the FFI can't marshal it) and the int8 domain builders are deliberately omitted from columns.ts. If released as-is, the notes direct users at a runtime FFI serialization failure and nonexistent types.Int8* members. Worth fixing before these changesets ship.

3. packages/stack/package.json (analyze:complexity) — the FTA gate was silently de-calibrated by the file split.
The --score-cap 72 was set as a <1-point buffer over the old monolith (71.08 — the gate-design doc explicitly prescribes "a small buffer, the way FTA sets --score-cap 72 against a current 71.08"). After the split the worst file (columns.ts) scores 67.83, so the gate now has ~4 points of slack — the exact regression class it was built to block would pass CI. Re-baseline to ~68–69 (and refresh the stale "71.08" claim in the spec doc, which this PR edited around).

4. src/eql/v3/columns.ts (EncryptedTextSearchColumn.build()) — unique/ore emission rules now live in two places.
The override hand-writes { unique: { token_filters: [] }, ore: {}, match: … } while indexesForCapabilities — which this PR just taught the text/HMAC rule — would produce the identical unique/ore shape for text_search's capabilities. The text_ord hm-index bug this PR fixed is the template for how divergence bites. Deriving via indexesForCapabilities and overriding only match is safe: the byte-identical build() unit tests would catch any drift.

5. src/eql/v3/columns.ts (freeTextSearch) vs src/schema/index.ts — the five-field match-opts merge is duplicated, and only v3 clones.
match-defaults.ts unified the default values but both freeTextSearch implementations still hand-copy the identical opts?.x ?? defaults.x merge. The copies already differ in one real way: v3 wraps in cloneMatchOpts, v2 stores the caller's nested tokenizer/token_filters objects by reference — mutating a shared opts object after calling v2's freeTextSearch leaks into the built schema. A shared resolveMatchOpts(opts) in match-defaults.ts collapses both and gives v2 the clone-on-write protection for free.

6. src/encryption/v3.ts (decryptModel/bulkDecryptModels) — table.build()'s duplicate-column throw escapes the Result contract. (plausible, edge-case)
rowReconstructor(table) calls table.build(), which throws on duplicate DB column names — surfacing as a promise rejection on the otherwise Result-shaped decrypt path. Only reachable by passing typedClient a table that wasn't in the client's init schemas (init validation catches the supported path), and encryptModel never builds at operation time, so the asymmetry only bites decrypt. Either catch-and-return { failure } or validate tables in typedClient (the ..._schemas rest param is currently captured and unused).

7. .github/workflows/fta-v3.yml — src/schema/match-defaults.ts sits outside the v3 gate scope it now feeds.
The extracted defaults directly shape every emitted v3 (and v2) match index block, but the workflow's paths: filters and the planned Stryker mutate scope cover src/eql/v3/** only, so edits to the defaults never trigger the v3 gates. One-line path addition; mainly matters for the eventual mutation gate, since k: 6, m: 2048 are load-bearing ciphertext parameters.

8. src/eql/v3/table.ts — V3DecryptedModel is character-for-character identical to V3ModelInput.
Both map columns to InferPlaintext<Table>[K] with identical nullability handling; V3EncryptedModel differs only in the mapped-to value. Keeping the semantic names is right, but export type V3DecryptedModel<…> = V3ModelInput<…> (or one shared mapped type parameterized on the value) prevents the input and output shapes from silently drifting when one copy is edited.

Noted but not counted

• rowReconstructor still rebuilds the table config on every decryptModel/bulkDecryptModels call — but the PR strictly improved this (previously per-row on the bulk path), so it's a pre-existing pattern; a per-table precompute in typedClient remains an easy follow-up.
• The implicit query-type flip for text_ord (unique now wins over ore in inferIndexType) was investigated and refuted as a regression: text_ord columns couldn't insert at all pre-PR, the behavior is test-asserted, and explicit queryType: 'orderAndRange' works — same documented escape hatch as text_search.

Automated multi-agent review (8 finder angles, per-candidate adversarial verification); findings verified against main post-merge.