Skip to content

stack: source EQL v3 type definitions from @cipherstash/eql instead of hand-maintaining them #695

Description

@coderdan

Summary

@cipherstash/stack's EQL v3 type surface — the per-domain storage/query types, the domain catalog, and the codec ids in packages/stack/src/eql/v3/ (types.ts, domain-registry.ts, columns.ts) — is hand-written. It does not import anything from @cipherstash/eql (which stack keeps only as a devDependency 3.0.0, used solely for the install SQL).

Meanwhile @cipherstash/eql already exports precise per-domain TypeScript types (storage + query shapes, ~130 of them — e.g. IntegerOrd = { v, i, c, op }, IntegerOrdQuery = { v, i, op }). Nothing in this repo imports them.

So the canonical EQL type definitions and stack's copy of them are two independent sources of truth that can silently drift. A new domain, a changed storage/query shape, or a new op in a future @cipherstash/eql release requires hand-editing stack's types to match — with nothing enforcing that they actually do.

Why it matters

  • Drift risk / correctness. stack's hand-written types can disagree with the EQL bundle they're meant to describe. A domain added or reshaped in EQL is invisible to stack's types.* catalog until someone manually mirrors it.
  • It's the reason prisma-next can't safely float EQL. prisma-next gets its entire v3 type surface from @cipherstash/stack (/eql/v3, /adapter-kit) and its install SQL from @cipherstash/eql. Because the types are hand-pinned in stack, the install SQL must be pinned exact to the same EQL release or the two diverge (see feat(prisma-next): source EQL v3 install SQL from @cipherstash/eql at runtime #694, which pins @cipherstash/eql exact for exactly this reason). If stack sourced its types from @cipherstash/eql, "an EQL version" would be a single coherent unit (types + SQL from one package).
  • Maintenance. Every EQL release currently needs a manual stack type update; the drivers (drizzle/supabase adapters, prisma-next) all inherit whatever stack hand-encodes.

Proposal

Have @cipherstash/stack/eql/v3 derive its domain catalog and per-domain storage/query types from @cipherstash/eql's exported types (promote @cipherstash/eql from devDep to a real dependency of stack, or a codegen step that regenerates types.ts/domain-registry.ts from the EQL package and fails CI on drift). Then the type surface and the install SQL both come from one pinned @cipherstash/eql, and a bump updates both coherently.

Scope / priority

Non-blocking for the current rc.2 / GA work — the hand-written types are correct against EQL 3.0.0 today, and #694 keeps prisma-next coherent by pinning exact. This is a structural cleanup to remove the drift risk and make EQL a single source of truth for both types and SQL.

Found while reviewing #694 (prisma-next runtime EQL-SQL sourcing).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions