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: 430392f

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: d50ff535-fba1-4812-8bdb-b01dcbcae82f

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]

What's the difference between BOOL and EncryptedBoolColumn?

[coderdan]

AFAIU, the domain types will basically get mapped into the same thing this fluent-builder does. But the test might be less brittle if we used a domain type here directly?

[coderdan]

Why is this hardcoded?

[coderdan]

Oh - because its not a real workspace ID. Carry on!

[coderdan]

Does this also address #530?

[coderdan]

This is pretty great tbh! We should make sure its documented in the Typedoc.

[tobyhede]

The merge semantics are documented in the JSDoc on freeTextSearch() (columns.ts:458-462): each provided key replaces its default, omitted keys keep the default, mirroring v2's opts?.x ?? default. There's currently no Typedoc pipeline in the repo — happy to set one up as a follow-up if that's what you're after.

[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.