refactor(stack): review wording/hygiene for v3 JSON (no behaviour change)

Addresses the PR #621 review's wording/classification/test-hygiene points
(design changes split to #622/#623):

- Sweep `ste_vec` out of user-facing comments/test names/skills →
  "encrypted JSONB document" / `eql_v3_json`; keep `ste_vec` only where it
  is literally the protect-ffi config key (`indexes.ste_vec`) or the
  `SteVecDocument` payload type.
- json-contains suite: drop the `makeEqlV3Column` wrapper (use the Drizzle
  `types.Json`), which lets both `as never` casts go (the pgTable and the
  bulkEncryptModels call) — the table is now properly typed; un-alias the
  Drizzle `eq`/`asc` imports.
- operators unit: rename `storageDomains` → `nonScalarQueryDomains` and fix
  the comment — json is a QUERYABLE (containment) domain that answers no
  scalar op, not a storage-only one.
- Reframe json's `deferred` marker across catalog/families/run-family-suite/
  test: it means "not run by the scalar op-matrix" (covered by dedicated
  suites), NOT unimplemented — distinct from the ORE domains' superuser-only
  deferral.
- Rewrite the opaque introspect comment as the explicit three-way case.
- Skill: describe JSON as containment-only today; mark JSONPath selector as
  not-yet-implemented (tracked in #623); note `JsonDocument` (no top-level
  scalar).

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

Author: coderdan

packages/stack/__tests__/drizzle-v3/operators.test.ts

@@ -115,18 +115,21 @@ const orderDomains = matrixEntries.filter(
   ([, spec]) => spec.indexes.ore || spec.indexes.ope,
 )
 const matchDomains = matrixEntries.filter(([, spec]) => spec.indexes.match)
-const storageDomains = matrixEntries.filter(
+// Domains with NO scalar query index (unique/ore/ope/match), so `eq`/`ne`/
+// ordering all throw. This is the truly storage-only scalar domains PLUS
+// `eql_v3_json` — json is a QUERYABLE domain (containment), it just answers no
+// scalar op, so it lands here for the eq/order rejection checks.
+const nonScalarQueryDomains = matrixEntries.filter(
   ([, spec]) =>
     !spec.indexes.unique &&
     !spec.indexes.ore &&
     !spec.indexes.ope &&
     !spec.indexes.match,
 )
-// Storage-only domains that also lack an ste_vec index: these reject `contains`
-// outright. A json (`ste_vec`) column is storage-only for eq/order but DOES
-// answer `contains` via `@>`, so it is excluded from the containment-rejection
-// group and covered by its own positive assertion below.
-const noContainmentDomains = storageDomains.filter(
+// Of those, the ones that also reject `contains` — i.e. everything except json.
+// json answers `contains` via `@>`, so it is excluded here and gets its own
+// positive assertion in the JSON containment describe above.
+const noContainmentDomains = nonScalarQueryDomains.filter(
   ([, spec]) => !spec.indexes.ste_vec,
 )
 
@@ -477,8 +480,8 @@ describe('createEncryptionOperatorsV3 - JSON containment', () => {
   })
 })
 
-describe('createEncryptionOperatorsV3 - storage-only domains', () => {
-  it.each(storageDomains)('%s eq throws', async (eqlType, spec) => {
+describe('createEncryptionOperatorsV3 - domains with no scalar query', () => {
+  it.each(nonScalarQueryDomains)('%s eq throws', async (eqlType, spec) => {
     const { ops } = setup()
     await expect(
       ops.eq(matrixColumn(eqlType), sampleFor(spec)),
@@ -492,7 +495,7 @@ describe('createEncryptionOperatorsV3 - storage-only domains', () => {
     ).rejects.toBeInstanceOf(EncryptionOperatorError)
   })
 
-  it.each(storageDomains)('%s asc throws synchronously', (eqlType) => {
+  it.each(nonScalarQueryDomains)('%s asc throws synchronously', (eqlType) => {
     const { ops } = setup()
     expect(() => ops.asc(matrixColumn(eqlType))).toThrow(
       EncryptionOperatorError,

packages/stack/__tests__/test-kit-families.test.ts

@@ -70,10 +70,11 @@ describe('test-kit families partition the v3 catalog', () => {
       'text_ord_ore',
       'timestamp_ord_ore',
     ])
-    // ORE domains defer for the superuser-only opclass; json defers because
-    // ste_vec containment isn't in the scalar op matrix.
+    // ORE domains defer for the superuser-only opclass; json defers because it
+    // is queried by containment, not the scalar op-matrix (covered by dedicated
+    // suites — see catalog reason).
     for (const { bare, reason } of deferred) {
-      expect(reason).toMatch(bare === 'json' ? /ste_vec/ : /superuser-only/)
+      expect(reason).toMatch(bare === 'json' ? /containment/ : /superuser-only/)
     }
   })
 

packages/stack/integration/drizzle-v3/json-contains.integration.test.ts

@@ -2,23 +2,24 @@
  * Live JSON containment for the v3 `types.Json()` column through the Drizzle
  * operators. Seeds encrypted JSONB documents and queries them with
  * `ops.contains(col, subObject)` — the same operator text search uses, but on a
- * `json` column it emits the `@>` operator over the ste_vec document (json has
- * no `eql_v3.contains` overload) with a `query_jsonb` needle from
+ * `json` column it emits the `@>` operator over the encrypted JSONB document
+ * (json has no `eql_v3.contains` overload) with a `query_jsonb` needle from
  * `encryptQuery` — asserting it returns exactly the rows whose document contains
  * the sub-object (jsonb `@>` semantics), and excludes the rest.
  */
 import { databaseUrl, unwrapResult } from '@cipherstash/test-kit'
-import { and, asc as drizzleAsc, eq as drizzleEq, type SQL } from 'drizzle-orm'
+import { and, asc, eq, type SQL } from 'drizzle-orm'
 import { integer, pgTable, text } from 'drizzle-orm/pg-core'
 import { drizzle } from 'drizzle-orm/postgres-js'
 import postgres from 'postgres'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
-import { EncryptionV3, types } from '@/encryption/v3'
+import { EncryptionV3 } from '@/encryption/v3'
+import type { JsonDocument } from '@/eql/v3'
 import {
   createEncryptionOperatorsV3,
   extractEncryptionSchemaV3,
+  types,
 } from '@/eql/v3/drizzle'
-import { makeEqlV3Column } from '@/eql/v3/drizzle/column'
 
 const sqlClient = postgres(databaseUrl(), { prepare: false })
 
@@ -29,13 +30,13 @@ const docTable = pgTable(TABLE_NAME, {
   id: integer('id').primaryKey().generatedAlwaysAsIdentity(),
   rowKey: text('row_key').notNull(),
   testRunId: text('test_run_id').notNull(),
-  doc: makeEqlV3Column(types.Json('doc')),
-} as never)
+  doc: types.Json('doc'),
+})
 
 const schema = extractEncryptionSchemaV3(docTable)
 
 // Distinct documents so each containment query has a definite expected set.
-const DOCS: Record<string, Record<string, unknown>> = {
+const DOCS: Record<string, JsonDocument> = {
   ada: { user: 'ada@example.com', roles: ['admin', 'eng'], active: true },
   grace: { user: 'grace@example.com', roles: ['eng'] },
   zoe: { user: 'zoe@example.com', roles: ['ops'], active: false },
@@ -50,8 +51,8 @@ async function matching(condition: SQL): Promise<string[]> {
   const rows = (await db
     .select({ rowKey: docTable.rowKey })
     .from(docTable)
-    .where(and(drizzleEq(docTable.testRunId, RUN), condition))
-    .orderBy(drizzleAsc(docTable.rowKey))) as SelectRow[]
+    .where(and(eq(docTable.testRunId, RUN), condition))
+    .orderBy(asc(docTable.rowKey))) as SelectRow[]
   return rows.map((row) => row.rowKey)
 }
 
@@ -77,7 +78,7 @@ beforeAll(async () => {
     doc,
   }))
   const encrypted = unwrapResult(
-    await client.bulkEncryptModels(rows as never, schema),
+    await client.bulkEncryptModels(rows, schema),
   ) as Array<Record<string, unknown>>
   await db.insert(docTable).values(encrypted as never)
 }, 120000)

packages/stack/integration/shared/json-crypto.integration.test.ts

@@ -1,8 +1,9 @@
 /**
  * Live round-trip for the v3 `types.Json()` column — an encrypted JSONB document
- * stored as an ste_vec `SteVecDocument`. Proves the new json column model
- * encrypts and decrypts a real document through protect-ffi (no DB query here;
- * containment is exercised by the Drizzle json suite).
+ * (`public.eql_v3_json`). Proves the new json column model encrypts and decrypts
+ * a real document through protect-ffi (no DB query here; containment is exercised
+ * by the Drizzle json suite). The stored payload is protect-ffi's
+ * `SteVecDocument`, carrying an `sv` array rather than a scalar `c` ciphertext.
  */
 import { unwrapResult } from '@cipherstash/test-kit'
 import { beforeAll, describe, expect, it } from 'vitest'
@@ -12,7 +13,7 @@ const docs = encryptedTable('v3_json_docs', {
   profile: types.Json('profile'),
 })
 
-describe('v3 typed client — JSON (ste_vec) round-trip', () => {
+describe('v3 typed client — encrypted JSONB round-trip', () => {
   let client: Awaited<ReturnType<typeof EncryptionV3<[typeof docs]>>>
 
   beforeAll(async () => {
@@ -30,7 +31,8 @@ describe('v3 typed client — JSON (ste_vec) round-trip', () => {
     const encrypted = unwrapResult(
       await client.encrypt(value, { table: docs, column: docs.profile }),
     )
-    // An ste_vec document carries an `sv` array, not a scalar `c` ciphertext.
+    // An encrypted JSONB document carries an `sv` array, not a scalar `c`
+    // ciphertext (the stored shape is protect-ffi's `SteVecDocument`).
     expect(Array.isArray((encrypted as { sv?: unknown }).sv)).toBe(true)
 
     const decrypted = unwrapResult(await client.decrypt(encrypted))
@@ -46,7 +48,7 @@ describe('v3 typed client — JSON (ste_vec) round-trip', () => {
 
   // A JSON document is not only an object: `types.Json` (and the `JsonDocument`
   // plaintext type) also admit a top-level array and `null`. Pin both so a
-  // regression in ste_vec encoding of non-object roots turns a test red.
+  // regression in encrypted-JSONB encoding of non-object roots turns a test red.
   it.each([
     ['array root', [1, 'two', { three: 3 }]],
     ['null root', null],

packages/stack/integration/supabase/introspect.integration.test.ts

@@ -28,10 +28,13 @@ beforeAll(async () => {
   // as unmodelled — it is an ordinary plaintext passthrough.
   await sql.unsafe(`DROP DOMAIN IF EXISTS public.${USER_DOMAIN}`)
   await sql.unsafe(`CREATE DOMAIN public.${USER_DOMAIN} AS jsonb`)
-  // Mixed EQL columns: `score` is typed with an EQL domain the SDK has NO types
-  // factory for (unmodelled → reported); `doc` is `eql_v3_json`, which `types.Json`
-  // DOES model (so it must be synthesized, not reported); `own` is a user's plain
-  // jsonb domain (plaintext passthrough, never reported).
+  // This table exercises all three cases the introspector must tell apart:
+  //   score → EQL domain (eql_v3_integer_ord_ope) the SDK has no factory for
+  //           → "unmodelled", MUST be reported so the caller knows it can't query it
+  //   doc   → EQL domain (eql_v3_json) the SDK models via types.Json
+  //           → modelled, MUST be synthesized and NOT reported
+  //   own   → a user's own plain jsonb domain with no EQL marker
+  //           → plaintext passthrough, MUST never be reported
   await sql.unsafe(`
     CREATE TABLE ${UNMODELLED} (
       id INTEGER PRIMARY KEY GENERATED ALWAYS AS IDENTITY,

packages/stack/src/eql/v3/columns.ts

@@ -369,10 +369,10 @@ function indexesForCapabilities(
   }
 
   if (capabilities.searchableJson) {
-    // Encrypted-JSONB (ste_vec) index. `prefix: 'enabled'` is a sentinel the
-    // table's `build()` rewrites to `${tableName}/${columnName}` — the same
-    // scheme v2 `searchableJson` uses — so each document's selectors are scoped
-    // to their column.
+    // Encrypted-JSONB index (the protect-ffi config kind is named `ste_vec`).
+    // `prefix: 'enabled'` is a sentinel the table's `build()` rewrites to
+    // `${tableName}/${columnName}` — the same scheme v2 `searchableJson` uses —
+    // so each document's selectors are scoped to their column.
     //
     // `array_index_mode` indexes array elements by identity (`item`) and enables
     // `$[*]` wildcard selectors, but deliberately drops `position`: `@>`
@@ -381,8 +381,8 @@ function indexesForCapabilities(
     // With positional terms emitted (v2 `searchableJson`'s `'all'`), the needle
     // for `x`-at-index-0 would miss a document holding `x` at index 1.
     //
-    // `mode: 'compat'` is REQUIRED for eql-3.0.0: `public.eql_v3_json` orders
-    // ste_vec entries by the CLLW-OPE `op` term, so the index must emit `op`
+    // `mode: 'compat'` is REQUIRED for eql-3.0.0: `public.eql_v3_json` orders the
+    // document's entries by the CLLW-OPE `op` term, so the index must emit `op`
     // (compat) terms. `'standard'` emits v2's CLLW-ORE `oc` terms, which the v3
     // domain rejects at encrypt time.
     indexes.ste_vec = {
@@ -633,10 +633,11 @@ const JSON_DOMAIN = {
 } as const
 
 /**
- * Builder for a `public.eql_v3_json` column — an encrypted JSONB document,
- * stored as an ste_vec `SteVecDocument` and queried by containment. The document
- * (any {@link JsonValue}) round-trips through `encrypt`/`decrypt`; structural
- * queries use the ste_vec index emitted by `build()`.
+ * Builder for a `public.eql_v3_json` column — an encrypted JSONB document
+ * (a {@link JsonDocument}: object, array, or null). It round-trips through
+ * `encrypt`/`decrypt`, and containment queries use the encrypted-JSONB index
+ * emitted by `build()`. (The stored payload is protect-ffi's `SteVecDocument`,
+ * and the config index kind is `ste_vec` — both protect-ffi names.)
  */
 export class EncryptedJsonColumn extends EncryptedV3Column<typeof JSON_DOMAIN> {
   constructor(columnName: string) {

packages/stack/src/eql/v3/drizzle/operators.ts

@@ -43,8 +43,11 @@ const MAX_IN_ARRAY_CONCURRENCY = 4
  *
  * `bulkEncrypt` is optional so a `{ encrypt }`-only client stays valid; the
  * list operators fall back to bounded-concurrency single encryption without it.
- * `encryptQuery` is likewise optional — only JSON containment (`@>`) needs it,
- * to build a `query_jsonb` needle; the `contains()` branch guards its absence.
+ * `encryptQuery` is optional only because today it is used by a single operator
+ * — JSON containment (`@>`), which needs a ciphertext-free `query_jsonb` needle;
+ * the `contains()` branch guards its absence. Every OTHER operator still encrypts
+ * its operand with `encrypt` (a full storage envelope). Unifying all operands
+ * onto `encryptQuery` — after which it stops being optional — is tracked in #622.
  */
 type OperandEncryptionClient = {
   encrypt(
@@ -233,9 +236,10 @@ export function createEncryptionOperatorsV3(
   const ORDERING_INDEXES = ['ore', 'ope'] as const
   // `contains` answers two shapes: bloom free-text (`match`, a `text_search`/
   // `text_match` column), which emits `eql_v3.contains(col, operand)`, and
-  // encrypted-JSONB containment (`ste_vec`, a `json` column), which emits the
-  // `@>` operator instead — json has no `eql_v3.contains` overload. The branch
-  // in `contains()` picks the right SQL by index kind.
+  // encrypted-JSONB containment (an `eql_v3_json` column, whose config carries
+  // the `ste_vec` index kind), which emits the `@>` operator instead — json has
+  // no `eql_v3.contains` overload. The branch in `contains()` picks the right SQL
+  // by index kind.
   const CONTAINMENT_INDEXES = ['match', 'ste_vec'] as const
 
   function applyOperationOptions(
@@ -448,7 +452,7 @@ export function createEncryptionOperatorsV3(
 
   /**
    * Build a `query_jsonb` containment needle for a `json` column. Uses
-   * `encryptQuery` (not `encrypt`): the ste_vec query term carries no ciphertext
+   * `encryptQuery` (not `encrypt`): the JSON query term carries no ciphertext
    * and satisfies the `eql_v3.query_jsonb` CHECK the `@>` overload needs.
    */
   async function encryptJsonContainmentTerm(

packages/test-kit/src/catalog.ts

@@ -668,11 +668,13 @@ export const V3_MATRIX = {
     errorSamples: NUM_ERR,
   },
 
-  // Encrypted JSONB document (ste_vec). DEFERRED from the scalar family driver:
-  // it is queried by containment/selector, not the eq/ord/match ops the oracle
-  // models, so it is covered by a dedicated json integration suite. The row
-  // still pins the built shape (`cast_as: 'json'` + the ste_vec index) and
-  // carries representative document samples.
+  // Encrypted JSONB document. Excluded from the SCALAR family driver (that is
+  // what `deferred` marks here) — NOT unimplemented: JSON is fully covered by
+  // its own live suites (`json-crypto`, `json-contains`). It is queried by
+  // containment (the `@>` operator), not the eq/ord/match ops the scalar oracle
+  // models, so `runFamilySuite` cannot exercise it. The row still pins the built
+  // shape (`cast_as: 'json'` + the encrypted-JSONB index) and carries
+  // representative document samples.
   'public.eql_v3_json': {
     builder: types.Json,
     ColumnClass: EncryptedJsonColumn,
@@ -695,7 +697,7 @@ export const V3_MATRIX = {
       { user: 'grace@example.com', roles: ['eng'] },
     ],
     deferred:
-      'json is queried by ste_vec containment/selector, not the scalar op ' +
-      'matrix — covered by a dedicated json integration suite',
+      'json is covered by dedicated live suites (json-crypto, json-contains), ' +
+      'not the scalar op-matrix: it is queried by containment, not eq/ord/match',
   },
 } as const satisfies Record<EqlV3TypeName, DomainSpec>

packages/test-kit/src/families.ts

@@ -47,10 +47,12 @@ const FAMILY_PREFIXES: Readonly<Record<FamilyName, readonly string[]>> = {
   timestamp: ['timestamp'],
   text: ['text'],
   boolean: ['boolean'],
-  // The json family's only domain (`eql_v3_json`) is `deferred`: ste_vec
-  // containment doesn't fit the scalar oracle, so it's covered by a dedicated
-  // suite, not `runFamilySuite`. The prefix still owns it for coverage
-  // accounting.
+  // `json` is here only for coverage accounting — its one domain (`eql_v3_json`)
+  // is marked `deferred`, meaning "not run by the scalar op-matrix", because JSON
+  // is queried by containment (`@>`), not the eq/ord/match ops the oracle models.
+  // It is NOT unimplemented: dedicated live suites (`json-crypto`, `json-contains`)
+  // cover it. (Contrast the ORE domains, also `deferred` but because their opclass
+  // is superuser-only and cannot run on managed Postgres.)
   json: ['json'],
 }
 

packages/test-kit/src/run-family-suite.ts

@@ -151,14 +151,13 @@ export function runFamilySuite(
   const adapter = makeAdapter()
   const domains = domainsForFamily(family)
 
-  // A family whose every domain is deferred (e.g. `json`: ste_vec containment
-  // and selector queries don't fit the scalar oracle this driver runs). It
-  // carries no op-matrix coverage here — its real coverage lives in dedicated
-  // suites (`json-crypto`, `json-contains`). Emit one assertion documenting the
-  // deferral so the family stays visible and is not a silent skip, rather than
-  // letting `planTable` throw on an empty column set. A family with NO domains
-  // at all (covered or deferred) is a wiring bug and still falls through to that
-  // throw.
+  // A family whose every domain is deferred (e.g. `json`: containment queries
+  // don't fit the scalar oracle this driver runs). It carries no op-matrix
+  // coverage here — its real coverage lives in dedicated suites (`json-crypto`,
+  // `json-contains`). Emit one assertion documenting the deferral so the family
+  // stays visible and is not a silent skip, rather than letting `planTable` throw
+  // on an empty column set. A family with NO domains at all (covered or deferred)
+  // is a wiring bug and still falls through to that throw.
   if (domains.length === 0) {
     const deferred = deferredForFamily(family)
     if (deferred.length > 0) {