Merge pull request #1095 from cipherstash/feat/eql-plan-targets

feat(stack-encrypt)!: EQL types as plan field targets, from Go through the guest

Author: coderdan

.cargo/mutants.toml

@@ -73,6 +73,10 @@ exclude_re = [
   'stack-encrypt/src/sem/mod\.rs:\d+:\d+: replace <impl MatchConfig for DefaultMatch>::options -> MatchOptions with Default::default\(\)$',
   # Both unit-context conversions explicitly return Self::default().
   'stack-encrypt/src/target/context\.rs:\d+:\d+: replace <impl From<\(\)> for (DeclaredContext|ExpectedContext<T>)>::from -> Self with Default::default\(\)$',
+  # The resolver of a build without EQL types holds none: its `targets` IS
+  # the empty list (`dynamic::target::NoTargets`), which a test asserts on
+  # and `resolve` turns into `TargetError::NoTargets`; `vec![]` is the body.
+  'stack-encrypt/src/dynamic/target\.rs:\d+:\d+: replace <impl TargetResolver for NoTargets>::targets -> Vec<TargetDescriptor> with vec!\[\]$',
 ]
 
 # Headroom over the measured baseline before a slow-but-correct mutant is

.changeset/eql-plan-field-targets.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**The `eql-bindings` crate resolves an EQL type named as a string to its own Stack Encrypt plan** (`stack-encrypt` feature). `eql_bindings::encryption::targets` carries a catalog-generated table of every EQL type a data plan may name as a field target — its name across languages, family and suffix, the plaintext `ValueKind` it takes, the indexes it carries, its query twin, and whether the engine can produce it today with the reason when not — and `encrypt` / `decrypt` / `query` entry points that dispatch on the name and run the type's derived `EncryptFrom` / `DecryptInto`, resolving to the EQL value's JSON bytes through the engine's `Pending` so a guest batches it with the rest of a plan. This is the EQL half of EQL types as plan field targets (cipherstash/stack#1062): a Go data plan names `TextEq` and the guest returns the finished EQL value instead of assembling one. `TextEq` is the only producible type; every other name is refused with the plan's reason. The SQL surface and the TypeScript package are unchanged.

.github/workflows/tests-golang.yml

@@ -8,8 +8,9 @@ name: Tests (Go)
 #   wasi-check  the stack crates build for wasm32-wasip1 with no JS-host or
 #               native-HTTP dependencies, the no-http shape passes its tests
 #               and docs, both guests pass lint and tests and are built with
-#               their import surfaces checked (the stack-encrypt guest twice:
-#               the real build and the deterministic-kms test build), their
+#               their import surfaces checked (the stack-encrypt guest four
+#               times: the real build, the build with the EQL types, and the
+#               deterministic-kms test build of each), their
 #               sha256 is recorded, `go:test` runs against them, and
 #               `go generate` leaves the tree unchanged.
 #   go-lint     golangci-lint, Linux only.
@@ -32,6 +33,9 @@ on:
       - packages/stack-encrypt/**
       - packages/stack-encrypt-derive/**
       - packages/stack-guest-abi/**
+      # The eql guest build links eql-bindings.
+      - packages/eql/crates/eql-bindings/**
+      - packages/eql/crates/eql-domains/**
       - languages/golang/**
       - scripts/check-wasm-imports.py
       - scripts/go-binding-test.sh
@@ -54,6 +58,9 @@ on:
       - packages/stack-encrypt/**
       - packages/stack-encrypt-derive/**
       - packages/stack-guest-abi/**
+      # The eql guest build links eql-bindings.
+      - packages/eql/crates/eql-bindings/**
+      - packages/eql/crates/eql-domains/**
       - languages/golang/**
       - scripts/check-wasm-imports.py
       - scripts/go-binding-test.sh
@@ -156,6 +163,18 @@ jobs:
       - name: stack-encrypt guest deterministic test build
         run: mise run wasm:guest:build:deterministic
 
+      # The build with the EQL types (ADR-0007, amended 2026-10-06), which
+      # package encrypt/eql embeds and registers on import, and its
+      # deterministic test build, which the hermetic tests of a TextEq field
+      # load. Same import-surface gate. The build task prints both builds'
+      # sizes: the plan asks for that measurement before the SDK settles on
+      # one build or two.
+      - name: stack-encrypt guest eql build and import-surface gate
+        run: mise run wasm:guest:build:eql
+
+      - name: stack-encrypt guest eql deterministic test build
+        run: mise run wasm:guest:build:eql:deterministic
+
       - name: Credential guest lint and tests
         run: mise run wasm:auth-guest:test
 
@@ -167,7 +186,7 @@ jobs:
       # same bytes rather than a stale or rebuilt guest.
       - name: Record the guests' checksums
         run: |
-          for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do
+          for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_deterministic.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do
             (cd languages/golang && openssl dgst -sha256 "$guest" | awk '{print $NF}' > "$guest.sha256" && echo "$guest sha256 $(cat "$guest.sha256")")
           done
 
@@ -180,6 +199,10 @@ jobs:
             languages/golang/encrypt/wasm/stack_encrypt_guest.wasm.sha256
             languages/golang/encrypt/testdata/stack_encrypt_guest_deterministic.wasm
             languages/golang/encrypt/testdata/stack_encrypt_guest_deterministic.wasm.sha256
+            languages/golang/encrypt/eql/wasm/stack_encrypt_guest_eql.wasm
+            languages/golang/encrypt/eql/wasm/stack_encrypt_guest_eql.wasm.sha256
+            languages/golang/encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm
+            languages/golang/encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm.sha256
             languages/golang/auth/wasm/stack_auth_guest.wasm
             languages/golang/auth/wasm/stack_auth_guest.wasm.sha256
           if-no-files-found: error
@@ -290,7 +313,7 @@ jobs:
       - name: The guests are the ones Linux built and checked
         run: |
           cd languages/golang
-          for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do
+          for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_deterministic.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do
             want=$(cat "$guest.sha256")
             got=$(openssl dgst -sha256 "$guest" | awk '{print $NF}')
             if [ "$want" != "$got" ]; then
@@ -356,7 +379,7 @@ jobs:
       - name: The guests are the ones the wasi-check job built and checked
         run: |
           cd languages/golang
-          for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do
+          for guest in encrypt/wasm/stack_encrypt_guest.wasm encrypt/testdata/stack_encrypt_guest_deterministic.wasm encrypt/eql/wasm/stack_encrypt_guest_eql.wasm encrypt/testdata/stack_encrypt_guest_eql_deterministic.wasm auth/wasm/stack_auth_guest.wasm; do
             want=$(cat "$guest.sha256")
             got=$(openssl dgst -sha256 "$guest" | awk '{print $NF}')
             if [ "$want" != "$got" ]; then

.gitignore

@@ -109,8 +109,10 @@ mutants.out/
 # The Go module's embedded WASI guests: build outputs of `mise run
 # wasm:guest:build` and `mise run wasm:auth-guest:build`.
 languages/golang/encrypt/wasm/*.wasm
+languages/golang/encrypt/eql/wasm/*.wasm
 languages/golang/auth/wasm/*.wasm
 languages/golang/encrypt/wasm/*.sha256
+languages/golang/encrypt/eql/wasm/*.sha256
 languages/golang/auth/wasm/*.sha256
 # The deterministic-kms TEST build of the stack-encrypt guest, from `mise run
 # wasm:guest:build:deterministic`; under testdata so no binary embeds it.

AGENTS.md

@@ -92,7 +92,7 @@ Every npm package except EQL lives under `languages/typescript/`: packages in `l
   links are provenance only.
 - `packages/stack-auth`, `packages/stack-profile`, `packages/stack-kms`, `packages/stack-encrypt`, `packages/stack-encrypt-derive`, `packages/stack-guest-abi`: The Rust crates imported from `cipherstash/cipherstash-suite` with their history — `stack-auth` and `stack-profile` (published to crates.io, one version group), `stack-kms` (published to crates.io from 0.1.0, its own version group, re-exported by `stack-encrypt` as `stack_encrypt::kms`), `stack-encrypt` and `stack-encrypt-derive` (published to crates.io from 0.1.0, one version group; `eql-bindings`' `stack-encrypt` feature depends on them from the registry), and `stack-guest-abi` (`publish = false`). They are the members of the **root Cargo workspace**, with the three node binding crates below. See "Working on the Rust crates".
 - `languages/typescript/packages/auth`, `languages/typescript/packages/profile`, `languages/typescript/packages/stack-auth-wasm`: The node bindings of those crates. `@cipherstash/auth` (napi-rs v2) and its six `platforms/*` packages are published to npm from this repository by `release.yml` (`auth-artifacts`, `publish-auth`); a change to what it ships, the `stack-auth` crate included, needs an `@cipherstash/auth` changeset (`require-auth-npm-changeset.yml`). `@cipherstash/profile` and its platforms are private and never published; `@cipherstash/stack-auth-wasm` is private and builds the wasm that `@cipherstash/auth` ships. Their `build` and `test` scripts never invoke cargo; `build:native`, `build:debug` and `test:cargo` do.
-- `languages/golang`: The Go module — the SDK `encrypt` with its generated-code support `encrypt/gensupport` and the policy packages `encrypt/policy` and `encrypt/policy/protosource`; the credential package `auth`; the generator `stashgen` and its command `cmd/stashgen`; and `internal` (the shared guest plumbing and the `record` wire model). A wazero host with no cgo. Its two WASI guests (`encrypt/guest`, `auth/guest`) are detached Cargo workspaces built by `mise run wasm:guest:build` and `mise run wasm:auth-guest:build`; `mise run wasm:guest:build:deterministic` builds the seeded TEST build the hermetic Go tests use; the `.wasm` files they embed are gitignored. Generated `*_stash.go` files are committed and CI fails when `go generate ./...` changes one. There is no Go release process yet.
+- `languages/golang`: The Go module — the SDK `encrypt` with its generated-code support `encrypt/gensupport` and the policy packages `encrypt/policy` and `encrypt/policy/protosource`; the credential package `auth`; the generator `stashgen` and its command `cmd/stashgen`; and `internal` (the shared guest plumbing and the `record` wire model). A wazero host with no cgo. Its two WASI guests (`encrypt/guest`, `auth/guest`) are detached Cargo workspaces built by `mise run wasm:guest:build` and `mise run wasm:auth-guest:build`; `mise run wasm:guest:build:deterministic` builds the seeded TEST build the hermetic Go tests use; the `.wasm` files they embed are gitignored. The stack-encrypt guest has a second build with the EQL types (`mise run wasm:guest:build:eql`, cargo feature `eql`, linking `eql-bindings` by path; `wasm:guest:build:eql:deterministic` is its test build), embedded by `encrypt/eql` and registered on import, so a program whose generated code names an EQL type runs it (ADR-0007, amended). `encrypt/eql`'s types and `Types` table are generated from the EQL catalog by `eql-codegen` (`eql_gen.go`, written by `mise run types:generate` in `packages/eql` and drift-gated by `types:check` and `cargo test -p eql-codegen`). Generated `*_stash.go` files are committed and CI fails when `go generate ./...` changes one. There is no Go release process yet.
 - `e2e/*`: Cross-package end-to-end tests (package managers, supply chain, Prisma example README)
 - `languages/typescript/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).

docs/plans/2026-10-04-plan-builder.md

@@ -667,6 +667,9 @@ The ciphertext inside it is a Stack Encrypt ciphertext, which starts with `stack
 "EQL v4" in this plan is the name of that form, and not a new envelope.
 
 The engine produces one EQL type today: `TextEq`.
+Status (2026-10-06, #1062): `TextEq` is producible through the data plan's target form.
+`stashgen` accepts `encrypt_into=TextEq`, the guest build with the EQL types returns the finished value, and `encrypt/eql` holds the generated Go types; every other type is listed by `se_targets` with the reason it is not producible, and `stashgen` refuses it.
+Open question for Dan: an EQL value is stored under a table and a column, so a target field's label must be exactly `<table>/<column>`; a cipher extended with a tenant part has no column for the extended label, and a plan with a target field refuses the extension rather than dropping it.
 The other types wait for work in the engine:
 
 - **Every family but `Text`:** how the family encodes a plaintext is not specified.

languages/golang/cmd/stashgen/README.md

@@ -21,8 +21,8 @@ Your program calls those functions, and it never builds or names a plan.
    type User struct {
    	_     struct{} `stash:"context=users"`
    	ID    int64    `stash:"id,passthrough"`
-   	Email string   `stash:"email,encrypt,index=equality;match"`
-   	Name  string   `stash:"name,encrypt"`
+   	Email string   `stash:"email,encrypt_into=TextEq"`
+   	Name  string   `stash:"name,encrypt_into=TextEq"`
    }
    ```
 
@@ -40,12 +40,11 @@ Your program calls those functions, and it never builds or names a plan.
    ```go
    encrypted, err := users.Encrypt(ctx, cipher, people)
    opened, err := users.Decrypt(ctx, cipher, encrypted)
-   term, err := users.Fields.Email.Equality(ctx, cipher, "bob@example.com")
+   query, err := users.Fields.Email.Query(ctx, cipher, "bob@example.com")
    ```
 
 6. Store the encrypted type.
-   Each sealed field is one or more byte columns: `Email.Ciphertext`, `Email.Equality`, `Email.Match`.
-   `encrypt.Ciphertext` and each term type implement `driver.Valuer` and `sql.Scanner`, so a database library binds and scans each one as bytes; map each one to its own column.
+   Each `encrypt_into` field is one EQL column: `eql.TextEq` implements `driver.Valuer` and `sql.Scanner`, so a database library binds and scans it as the JSON a `public.eql_v3_text_eq` column holds.
 
 7. Run the generator again after each change to the struct or to a tag.
    A change to the fields of the struct stops the build until you do.
@@ -148,10 +147,14 @@ It ignores its own output file when it loads the package, so a stale file does n
 The same input always gives the same file: fields keep their declared order, and the file carries no version and no time.
 
 `stashgen` checks each declaration with the engine, and holds no copy of the engine's rules: it runs the WASI guest the SDK embeds and asks it, one field at a time, so the error names the field.
-It asks the engine for the EQL types it holds: each name, its plaintext type, its indexes and its query form.
-This build of the engine produces no EQL type, so `encrypt_into` is refused with "EQL types are not available yet"; the next release adds `TextEq` and `encrypt/eql`.
+It asks the engine for the EQL types it holds: each name, its plaintext type, its indexes, its query form, and whether the engine produces it today.
+The command links the build of the engine that holds the EQL types (`encrypt/eql`), so it can answer for every type; a generated file imports `encrypt/eql` only when it names one.
+The engine produces `TextEq` today; `encrypt_into` with any other type is refused with the type's name.
 Separate columns work today for four indexes: `equality`, `match`, `ore` and `ope`.
 
+A field with `encrypt_into` is stored under its table and column, which is what an EQL value records in its `i`.
+A cipher extended with a tenant part (`cipher.Extend(...)`) has no column for the extended label, so it refuses a struct with an `encrypt_into` field; use `index=` columns for a tenant-extended struct until that rule is settled.
+
 ## When stashgen stops
 
 `stashgen` stops with an error, and writes no file, for each of these.
@@ -225,5 +228,5 @@ A protobuf message with a `oneof` cannot be generated from a policy: protoc-gen-
 
 ## Status
 
-The command runs the WASI guest the SDK embeds, so it needs the guest built: `mise run wasm:guest:build`.
+The command runs the WASI guest the SDK embeds, so it needs the guests built: `mise run wasm:guest:build wasm:guest:build:eql`.
 The library, `github.com/cipherstash/stack/languages/golang/stashgen`, takes any `Engine`; `stashgen.Generate` takes one with `WithEngine`, and `stashgen/enginetest` has a static one for tests.

languages/golang/cmd/stashgen/main.go

@@ -15,6 +15,11 @@ import (
 	"os"
 	"strings"
 
+	// The build of the engine that holds the EQL types: the generator
+	// asks the embedded guest which EQL types it produces, so it links the
+	// build that has them. Generated code imports encrypt/eql only when it
+	// names one.
+	_ "github.com/cipherstash/stack/languages/golang/encrypt/eql"
 	"github.com/cipherstash/stack/languages/golang/stashgen"
 )