docs(golang): show the query methods, the database/sql query and the decrypt-and-verify step, and say se_query is gone

The README and the package documentation describe one method per
operator, what each returns, why a matches query carries Verify and
TargetLimit and an exact one neither, and that a MatchQuery holds its text
because Go cannot wipe a string. The ADR-0007 amendment records
se_operators, the removal of se_query, and the one reason se_term stays.

Part of #1189

Author: coderdan

languages/golang/cmd/stashgen/README.md

@@ -40,7 +40,7 @@ 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)
-   query, err := users.Fields.Email.Query(ctx, cipher, "bob@example.com")
+   query, err := users.Fields.Email.Eq(ctx, cipher, "bob@example.com")
    ```
 
 6. Store the encrypted type.
@@ -123,7 +123,12 @@ For `-type User`, the file `user_stash.go` holds:
 - `Encrypt` and `Decrypt`, which take a slice and return a slice, and send one ZeroKMS request for each 500 sealed values in it, plus one the first time a keyset is used.
 - `Fields`, with one entry for each sealed field.
   An opaque struct, or a struct with no sealed field outside an opaque one, gets no `Fields`: nothing in it is sealed on its own, so nothing can be queried.
-  An entry encrypts one value, and it has a query method only for what the field declares: `Query` for `encrypt_into`, and `Equality`, `Match`, `Ore` or `Ope` for `index=`.
+  An entry encrypts one value, and has one query method for each operator the engine answers on the field: `Eq`, `Lt`, `Lte`, `Gt`, `Gte`, `Between` or `Matches`.
+  stashgen asks the embedded engine which operators each field answers, and which index answers each one, so it holds no copy of those rules: an equality index answers `Eq`, a match index on a string `Matches`, and an ORE or OPE index on an integer the four orderings and `Between`, through ORE when the field declares both.
+  `encrypt_into=TextEq` answers `Eq`, which returns the type's query value, `eql.TextEqQuery`.
+  `encrypt_into=TextMatch` answers `Matches`, which returns an `encrypt.EQLMatchQuery`: the `eql.TextMatchQuery` operand, with `Verify` and `TargetLimit`.
+  The query of `Matches` carries `Verify` and `TargetLimit`, because its answer can hold rows that do not match; an exact operator's query carries neither.
+  See the encrypt package's README for each method's result and the query with `database/sql`.
 - `String` and `LogValue` on `EncryptedUser`, which print the passthrough fields and hide the sealed ones.
 - A copy of the fields of `User`, so a change to them stops the build.
 

languages/golang/encrypt/README.md

@@ -60,11 +60,13 @@ The package reference is on [pkg.go.dev]; the generator's reference is
 
    encrypted, err := users.Encrypt(ctx, cipher, people)
    opened, err := users.Decrypt(ctx, cipher, encrypted)
-   query, err := users.Fields.Email.Query(ctx, cipher, "bob@example.com")
+   term, err := users.Fields.Email.Eq(ctx, cipher, "bob@example.com")
    ```
 
    `Encrypt` and `Decrypt` send one ZeroKMS request for each 500 sealed
    values in the batch, plus one request the first time a keyset is used.
+   A query derives its term locally and sends no request; see
+   [Queries](#queries).
 
 6. Store the encrypted type. Each `encrypt_into` field is one EQL v4 column:
    `eql.TextEq` implements `driver.Valuer` and `sql.Scanner`, so a database
@@ -211,7 +213,7 @@ the value is one of those. A match *query* of such text is refused with
 `TextMatch` field is stricter, as "EQL columns" below says.
 
 Terms are byte-equal to the ones the Rust crate derives, so a term from
-`users.Fields.Email.Equality` compares against a stored term written from any
+`users.Fields.Email.Eq` compares against a stored term written from any
 language. `EqualityTerm.Equal` compares in constant time; `OreTerm.Compare`
 and `OpeTerm.Compare` order as the plaintexts; `MatchTerm.Positions` decodes
 the token positions.
@@ -224,8 +226,88 @@ A database can compare some terms by itself:
 - `Ore`: do not compare in SQL. Plain byte order is almost always right, and
   sometimes wrong, with no error. Compare in Go with `OreTerm.Compare`, or
   use an EQL type (`encrypt_into=`), which the database compares correctly.
-- `Match`: do not compare in SQL. Decode the positions in Go with
-  `MatchTerm.Positions`, or use an EQL type.
+- `Match`: a row matches when its stored filter holds every position of the
+  query's term. Decode both into positions in SQL and compare with `@>`, as
+  [Queries](#queries) shows, or in Go with `MatchTerm.Positions`.
+
+## Queries
+
+Each sealed field's entry in `Fields` has one method for each operator the
+engine answers on the field: `Eq`, `Lt`, `Lte`, `Gt`, `Gte`, `Between` and
+`Matches`. A field has no method for an operator it does not answer, so such
+a query does not compile. The generator asks the engine which operators each
+field answers, and which index answers each one; it holds no copy of those
+rules.
+
+| The field declares | Methods | Each returns |
+|---|---|---|
+| `index=equality` | `Eq` | `encrypt.EqualityTerm` |
+| `index=ore` or `index=ope`, on an integer | `Lt`, `Lte`, `Gt`, `Gte` | `encrypt.OreTerm`, or `encrypt.OpeTerm` when the field declares no `ore` |
+| the same | `Between(ctx, cipher, lo, hi)` | `encrypt.Range[encrypt.OreTerm]` or `encrypt.Range[encrypt.OpeTerm]`, the two bounds' terms |
+| `index=match`, on a string | `Matches` | `encrypt.MatchQuery[T]` |
+| `encrypt_into=TextEq` | `Eq` | `eql.TextEqQuery` |
+
+A method takes the field's own Go type, so `Fields.Age.Lt` on a `uint32`
+field takes a `uint32`. An order index on text, bytes or a float stores its
+term but answers no ordering operator yet, so such a field has no `Lt`.
+
+Every query type implements `driver.Valuer`, so it binds as a parameter in
+any library built on `database/sql` or pgx. A `Range` binds as two
+parameters, `Low` and `High`.
+
+`Eq`, the orderings and `Between` are exact: the server's answer is the
+answer. `Matches` is probabilistic: the server answers with every row whose
+stored filter holds the query's bits, which can include rows that do not
+hold the query's text. So `MatchQuery` carries two more methods, and an
+exact query's type carries neither (on an `encrypt_into=TextMatch` field,
+`Matches` returns an `encrypt.EQLMatchQuery`, the `eql.TextMatchQuery`
+operand with the same two):
+
+- `TargetLimit(ctx, want, stats)` is how many rows to fetch for `want` of
+  them to verify. A field declared with tags states no expected number of
+  tokens, so with no measured histogram of the stored filters in
+  `encrypt.Stats` the limit is unbounded, and `Limit.FetchOr(page)` fetches
+  a page.
+- `Verify(ctx, values)` says, for each decrypted value of a page, whether it
+  really holds the query's text: one call into the engine for the page, with
+  no key.
+
+```go
+// Positions of a stored filter or a match term, for @>.
+const positions = `CREATE FUNCTION match_positions(term bytea) RETURNS int[]
+LANGUAGE sql IMMUTABLE STRICT AS $$
+  SELECT coalesce(array_agg(get_byte(term, 2 * i) | (get_byte(term, 2 * i + 1) << 8)), '{}')
+  FROM generate_series(0, length(term) / 2 - 1) AS i
+$$`
+
+q, err := users.Fields.Email.Matches(ctx, cipher, "alice")
+limit, err := q.TargetLimit(ctx, 10, encrypt.Stats{Rows: rowCount})
+
+rows, err := db.QueryContext(ctx, `
+	SELECT id, email, email_eq, email_match, age, age_eq, age_ore FROM users
+	WHERE match_positions(email_match) @> match_positions($1)
+	ORDER BY id LIMIT $2`, q, limit.FetchOr(50))
+// scan each row into a users.Encrypted, then
+people, err := users.Decrypt(ctx, cipher, encrypted)
+emails := make([]string, len(people))
+for i, p := range people {
+	emails[i] = p.Email
+}
+verified, err := q.Verify(ctx, emails)
+hits := people[:0]
+for i, p := range people {
+	if verified[i] {
+		hits = append(hits, p)
+	}
+}
+```
+
+`Verify` cuts the query's text into tokens again in the engine, with the
+field's own tokenizer, so a `MatchQuery` keeps that text for as long as the
+program holds the query. Go cannot wipe a string: the text stays in memory
+until the garbage collector reclaims it, as the string you passed in does.
+A `MatchQuery` never prints it; `fmt`, `slog` and `%#v` show the field and
+the size of the term only.
 
 ## Errors
 
@@ -318,8 +400,11 @@ the catalog (ordering, dates, decimals, JSON) is listed in
 with that reason. The guest builds the value: the generated code
 imports `encrypt/eql`, which embeds the build of the engine that holds the
 EQL types and registers it on import, so the program runs that build and
-stores what it returns. `Fields.Email.Query` returns the `eql.TextEqQuery`
-the column's `eql_v4.query_text_eq` operand takes. `mise run
+stores what it returns. `Fields.Email.Eq` returns the `eql.TextEqQuery`
+the column's `eql_v4.query_text_eq` operand takes; `TextEq` answers `eq`
+alone, and a `TextMatch` field's `Matches` returns an
+`encrypt.EQLMatchQuery`: the `eql.TextMatchQuery` operand with `Verify` and
+`TargetLimit`. `mise run
 wasm:guest:build:eql` builds that guest beside the other. A cipher extended
 with a tenant part refuses a struct with an `encrypt_into` field: an EQL
 value is stored under a table and a column, and the extended label has no

languages/golang/encrypt/doc.go

@@ -40,10 +40,11 @@
 //	cipher := client.Keyset(encrypt.KeysetName("tenant-42"))
 //	encrypted, err := users.Encrypt(ctx, cipher, people) // []users.EncryptedUser
 //	opened, err := users.Decrypt(ctx, cipher, encrypted) // []users.User
-//	query, err := users.Fields.Email.Query(ctx, cipher, "bob@example.com")
+//	term, err := users.Fields.Email.Eq(ctx, cipher, "bob@example.com")
 //
 // Encrypt and Decrypt send one ZeroKMS request for each 500 sealed values in
-// the batch, plus one the first time a keyset is used.
+// the batch, plus one the first time a keyset is used. A query derives its
+// term with no request; see Queries below.
 //
 // 6. Store the encrypted type. Each encrypt_into field is one EQL v4 column
 // (an eql.TextEq goes in a public.eql_v4_text_eq column), implementing
@@ -124,6 +125,46 @@
 // refused with [ErrTerm], because an empty filter as a query would match every
 // row.
 //
+// # Queries
+//
+// A generated Fields entry has one method for each operator the engine
+// answers on the field, named for it: Eq, Lt, Lte, Gt, Gte, Between and
+// Matches. A field has no method for an operator it does not answer, so
+// such a query does not compile; the generator asks the engine which
+// operators each field answers, and holds no copy of the rules. Each method
+// takes the field's own Go type.
+//
+// Eq returns an [EqualityTerm] (or, for a field with encrypt_into, the EQL
+// type's query value), an ordering an [OreTerm] or [OpeTerm], and Between a
+// [Range] of two. Their answers are exact. Matches returns a [MatchQuery],
+// whose answer can hold rows that do not match: size the fetch with
+// [MatchQuery.TargetLimit], then decrypt the rows and keep those
+// [MatchQuery.Verify] reports true, one call into the engine for the page.
+// On a field with encrypt_into=TextMatch, Matches returns an
+// [EQLMatchQuery], the type's query value with the same two methods.
+// Every query type implements driver.Valuer, so it binds as a parameter
+// through database/sql or pgx:
+//
+//	q, err := users.Fields.Email.Matches(ctx, cipher, "alice")
+//	limit, err := q.TargetLimit(ctx, 10, encrypt.Stats{Rows: rowCount})
+//	rows, err := db.QueryContext(ctx, `SELECT id, email, email_eq, email_match, age, age_eq, age_ore
+//		FROM users WHERE match_positions(email_match) @> match_positions($1)
+//		ORDER BY id LIMIT $2`, q, limit.FetchOr(50))
+//	// scan into []users.EncryptedUser, then
+//	people, err := users.Decrypt(ctx, cipher, encrypted)
+//	emails := make([]string, len(people))
+//	for i, p := range people {
+//		emails[i] = p.Email
+//	}
+//	verified, err := q.Verify(ctx, emails) // one bool per row
+//
+// match_positions is a SQL function of your own that reads a match term's
+// little-endian uint16 positions into an int[]; the package README has one.
+// A MatchQuery keeps the text it was derived from, because Verify cuts its
+// tokens again in the engine. Go cannot wipe a string, so the text stays in
+// memory until the garbage collector reclaims it; a MatchQuery never prints
+// it.
+//
 // # Transport and auth
 //
 // The guest imports exactly two host functions: an HTTP send, served by any

languages/golang/encrypt/eql/eql.go

@@ -3,7 +3,7 @@
 // the type's domain, and the query types that match them.
 //
 // A field with `stash:"email,encrypt_into=TextEq"` is an [TextEq] in the
-// generated encrypted type, and its Fields entry's Query returns a
+// generated encrypted type, and its Fields entry's Eq returns a
 // [TextEqQuery]. The guest builds every value: generated code stores what
 // the guest returns and never assembles an EQL value itself (ADR-0007,
 // amended 2026-10-06). Each type implements driver.Valuer and sql.Scanner

languages/golang/encrypt/example/README.md

@@ -2,7 +2,7 @@
 
 A runnable tour of the Go SDK against real ZeroKMS: declare a struct with
 `stash` tags, generate its encrypted type, seal a batch in one request, derive
-a query term, and open the batch again.
+a query term, open the batch again, and verify a matches query over it.
 
 ## Running it
 
@@ -28,5 +28,5 @@ until they are built.
 - `model.go`: the struct and its `go:generate` line.
 - `user_stash.go`: what `stashgen` wrote from the tags. Regenerate it with
   `go generate ./...`; CI fails when that changes a committed file.
-- `main.go`: `Encrypt`, `Fields.Email.Equality` and `Decrypt`, the only three
-  calls a program makes.
+- `main.go`: `Encrypt`, `Fields.Email.Eq`, `Decrypt`, and `Fields.Email.Matches`
+  with `Verify` on the decrypted rows.

languages/golang/encrypt/guest/src/ops.rs

@@ -409,7 +409,7 @@ pub fn targets() -> Result<Vec<u8>, u32> {
 /// The operators one field of a codec-encoded plan answers, as a
 /// codec-encoded list: one object per operator, in the order the engine
 /// lists them, each written by
-/// [`dynamic::operator_to_value`](stack_encrypt::dynamic::operator_to_value):
+/// [`dynamic::operator_to_value`]:
 ///
 /// ```text
 /// [ { "operator": "eq", "fidelity": "exact", "arity": "one", "index": "eq" }, ... ]

packages/stack-encrypt/docs/adr/0007-bindings-enter-through-a-plan-never-a-second-executor.md

@@ -292,10 +292,20 @@ from Go and the typed query chain derive the same bytes. A cross-language
 fixture holds them together (`tests/fixtures/query_operators.json`): the Rust
 side checks each recorded term against the typed chain, and the Go SDK's
 tests derive, verify and size the same queries through the guest.
-`se_query`, which derives a target field's twin with no operator, stays until
-the generated Go code names operators (#1189), and is removed then.
-`se_term`, a term by index under an explicit context, stays for the generated
-code of fields declared with indexes until that code names operators too.
+The catalog answers for an EQL type; a field declared with indexes has no
+type to look up, so `se_operators` answers for any field of a plan: the
+plan and the field's name in, the same operator objects out, computed by the
+one table `se_query_term` reads (`dynamic::field_operators`). The Go
+generator asks it for every sealed field, `encrypt_into` fields included,
+and writes one method per operator (#1189).
+
+`se_query`, which derived a target field's twin with no operator, is
+removed: the generated Go code names operators (#1189), and `eq` on a target
+field is the twin. `se_term`, a term by index under an explicit context, no
+longer serves a query. It stays for one host need: a record call's term
+failure does not say which row and field it came from, and the Go SDK asks
+`se_term` again for each term to name them. When the record exports name the
+field themselves, it goes too.
 
 A data plan's match index declares no `expected_tokens` prior, so
 `target_limit` on a field declared as data is unbounded without a measured