fix(stack-encrypt): address the review of the tuple, nullable and record field markers

OreBlockTerm had no LabelledTarget impl, so a block ORE field, alone or
beside an equality index, had a marker with no operator method. It is
sealed under the caller's context like the other order terms.

field() now bounds the inner record's scope with NestedScope, so an
inner record with a scope of its own is refused with a message that
says why, rather than a bare type mismatch. QueryValue is sealed for
every type parameter. Root's outer labels are pushed by an empty method,
so no equivalent mutant is left for the mutants gate.

The docs say that an untyped nullable marker takes an Option, and that
None derives a term no row holds; query = .. refuses it, and a ui case
pins that. The tests add a caller binding and stored bindings around a
nested record, an outer field under another identity, a nullable field
of two indexes, an empty nested scope, block ORE, and the chain's tuple
query without .via. The CHANGELOG describes the final Marker.

Refs #1596

Author: coderdan

docs/plans/2026-10-24-stack-encrypt-api-plan.md

@@ -1573,7 +1573,7 @@ review.
   it, so the marker's index list is its target type's `Answers` impls.
   Pull request #1595 lands the markers, their query methods and
   `assert_context!` over a marker (`src/marker.rs`, `tests/markers.rs`,
-  `tests/ui/marker_*.rs`). The fix for #1596 gives a field of several
+  `tests/ui/marker_*.rs`). Pull request #1599 gives a field of several
   indexes, a nullable field and a record field their operator methods,
   and a field its query type (`#[stash(query = ..)]`). The chain query
   `cipher.query(op, value).on(&plan)` still exists until #1488 removes
@@ -1590,8 +1590,8 @@ review.
   lands with the builder's removal. The dynamic grammar keeps its
   run-time checks.
 - **Tracked in.** Issue #1486 is open; pull request #1595 closes it.
-  Issue #1596, the operator methods the markers lacked, is closed by the
-  pull request stacked on #1597.
+  Issue #1596, the operator methods the markers lacked, is closed by
+  pull request #1599.
 - **Finished when** these are all true:
   - the [marker example](#query-a-record-field) compiles, with the
     index's query term as the output type; the EQL query types come

packages/stack-encrypt-derive/src/attrs.rs

@@ -340,7 +340,8 @@ pub(crate) struct FieldAttrs {
     /// `#[stash(query = String)]`: with `struct = ..`, the type a query of
     /// this field takes, so its marker's methods take that type alone. The
     /// derive checks it against the plaintext field, which is that type or
-    /// an `Option` of it.
+    /// an `Option` of it. On a field whose marker has no operator method
+    /// (a record field, a ciphertext alone), only the check applies.
     pub(crate) query: Option<Type>,
 }
 

packages/stack-encrypt-derive/src/lib.rs

@@ -140,7 +140,9 @@
 //! it against the plaintext struct's field, which is that type or an
 //! `Option` of it. Without it, an equality marker takes any type its index
 //! accepts, since the derive does not see the plaintext struct's field
-//! types otherwise. A record that lists a caller scope
+//! types otherwise. On a field whose marker has no operator method, such
+//! as a record field or a `StackCipherText`, it does nothing beyond that
+//! check. A record that lists a caller scope
 //! gives its markers that scope's type, and the query takes it with
 //! `.scope(..)`, once; a record with none gives a query that is ready at
 //! once. No binding can be given. The query ends with `.encrypt(&keyset)`

packages/stack-encrypt/CHANGELOG.md

@@ -9,40 +9,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Field markers** (#1486, #1590). `#[derive(EncryptTarget)]` on a
-  `struct = ..` record emits one `Marker` per derived field. It is an
+- **Field markers** (#1486, #1590, #1596). `#[derive(EncryptTarget)]` on
+  a `struct = ..` record emits one `Marker` per derived field. It is an
   associated constant named after the field in upper case:
-  `EncryptedUser::EMAIL`. A marker names the field, the context the derive
-  sealed it under, and the field's target type. It also names the type of
-  the scope the record's caller supplies. Its methods are one per operator the field's
-  index answers, checked at compile time through `Answers`: `eq`, `lt`,
-  `lte`, `gt`, `gte`, `between`, and `matches`. A record that lists a
-  caller scope, `scope(tenant: u64)`, gives a query with no `encrypt`
-  until `.scope(..)` is given once, with a `Scope<u64>`. A record with no
-  caller scope gives a query that is ready at once. The query has no
-  `bind` method, and ends with `.encrypt(&keyset)`. The output is the
-  index's query term. A query from a marker derives under the declaration
-  the derive wrote, so it is the stored term. No plan is written by hand
-  beside the record. The query's copy of the value is wiped when it is
-  derived, refused, or dropped. `assert_context!` takes a marker, and
-  `Marker::contexts()` is the record's contexts narrowed to the field.
-  A tuple field has no marker.
-- **Markers for fields of several indexes, nullable fields, and record
-  fields** (#1596). A field of several indexes,
-  `Encrypted<(EqualityTerm, MatchTerms)>`, answers each operator through
-  the one index that answers it. Each term states its answer to each
-  operator with `op::OperatorAnswer`. An operator that no index answers,
-  or that two answer, has no method. An `Option<..>` field answers what a
-  present value answers, and a present value's term is a bare value's.
-  `EncryptedAccount::ADDRESS.field(EncryptedAddress::STREET)` is the
-  inner field's marker under the outer field's context. It takes the
-  outer record's scope, and only a marker of the record the field holds.
-  `#[stash(query = String)]` states the type a field's queries take, so
-  `EMAIL.eq(&42u64)` no longer compiles on a text field. The derive checks
-  the type against the plaintext struct's field. `Marker` now has the
-  parameters `Marker<W, T, C, P>`: `W` is where the field sits
-  (`marker::Root<R>` or `marker::Nested<W>`), and `P` is the query type
-  (`marker::TakesAny` or `marker::Takes<V>`).
+  `EncryptedUser::EMAIL`. A marker is `Marker<W, T, C, P>`. `W` is where
+  the field sits: `marker::Root<R>` for a field of the record `R`, or
+  `marker::Nested<W>` for one reached through a record field. `T` is the
+  field's target type. `C` is the scope the record's caller supplies.
+  `P` is the type a query takes: `marker::TakesAny`, or `marker::Takes<V>`
+  for a field marked `#[stash(query = V)]`.
+  - Its methods are one per operator the field's indexes answer, checked
+    at compile time through `Answers`: `eq`, `lt`, `lte`, `gt`, `gte`,
+    `between`, and `matches`. A field of several indexes,
+    `Encrypted<(EqualityTerm, MatchTerms)>`, answers each operator through
+    the one index that answers it. Each term states its answer with
+    `op::OperatorAnswer`. An operator no index answers, or two answer, has
+    no method. An `Option<..>` field has the methods a present value has.
+  - `EncryptedAccount::ADDRESS.field(EncryptedAddress::STREET)` is the
+    inner field's marker under the outer field's context. It takes the
+    outer record's scope. `field` accepts only a marker of the inner record.
+  - `#[stash(query = String)]` states the type a field's queries take. The
+    derive checks it against the plaintext struct's field.
+  - A record that lists a caller scope, `scope(tenant: u64)`, gives a
+    query with no `encrypt` until `.scope(..)` is given once, with a
+    `Scope<u64>`. A record with no caller scope gives a query that is
+    ready at once. The query has no `bind` method, and ends with
+    `.encrypt(&keyset)`. The output is the index's query term.
+  - A query from a marker derives under the declaration the derive wrote,
+    so it is the stored term. No plan is written by hand beside the
+    record. The query's copy of the value is wiped when it is derived,
+    refused, or dropped. `assert_context!` takes a marker, and
+    `Marker::contexts()` is the record's contexts narrowed to the field.
+    A tuple field has no marker.
+- **Tuples of terms answer the query chain too** (#1596). A query of
+  `op::Eq` or `op::Matches` on a plan of
+  `Encrypted<(EqualityTerm, MatchTerms)>` needs no `.via(index)`. The
+  query uses the one term that answers the operator. `OreBlockTerm` implements `LabelledTarget`, so a block ORE field
+  is queried under its label.
 - **`dynamic::Planned`, a value under a plan that is data** (#1486). A
   record under a `Plan`, or a query value under a `QueryPlan`, each a
   `ValueFrame`, is a target in the owned API's sense. `StackCipherText`

packages/stack-encrypt/src/marker.rs

@@ -97,7 +97,7 @@
 //! `Outer::ACCOUNT.field(EncryptedAccount::ADDRESS).field(EncryptedAddress::STREET)`.
 //! The inner record must list no scope of its own, stored or supplied: a
 //! query of it would take two scopes, and `field` takes a marker whose
-//! scope is [`NoScope`].
+//! scope is [`NoScope`] ([`NestedScope`]).
 //!
 //! # The type a query takes
 //!
@@ -109,6 +109,12 @@
 //! type alone ([`Takes`]), and the derive checks it against the plaintext
 //! struct's field, which is that type or an `Option` of it. An order marker
 //! fixes the type without the attribute, since `OreTerm<S>` names it.
+//!
+//! A nullable field's marker without the attribute also takes an `Option`,
+//! since the equality index accepts one. `NICK.eq(&None::<String>)`
+//! compiles and derives a term that no stored row holds: a `None` field
+//! stores no term, and a marker query is never `IS NULL`. Mark the field
+//! `#[stash(query = String)]` to refuse it.
 use std::marker::PhantomData;
 
 use stack_kms::MaybeSend;
@@ -158,7 +164,7 @@ impl<W: Place, T, C, P> std::fmt::Debug for Marker<W, T, C, P> {
             .field("name", &self.name)
             .field("scope", &self.scope)
             .field("identity", &self.identity)
-            .field("within", &self.place.outers())
+            .field("within", &outers(&self.place))
             .finish_non_exhaustive()
     }
 }
@@ -221,8 +227,12 @@ impl<W: Place, T, C, P> Marker<W, T, C, P> {
     ///
     /// `inner` must be a marker of the record `T` this field holds, so a
     /// marker of another record does not compile. That record must list no
-    /// scope of its own ([`NoScope`]): a query of it would take two scopes.
-    pub fn field<U, Q>(self, inner: Marker<Root<T>, U, NoScope, Q>) -> Marker<Nested<W>, U, C, Q> {
+    /// scope of its own ([`NestedScope`]): a query of it would take two
+    /// scopes.
+    pub fn field<U, C2: NestedScope, Q>(
+        self,
+        inner: Marker<Root<T>, U, C2, Q>,
+    ) -> Marker<Nested<W>, U, C, Q> {
         Marker {
             name: inner.name,
             scope: inner.scope,
@@ -246,7 +256,7 @@ impl<W: Place, T, C, P> Marker<W, T, C, P> {
     {
         MarkedQuery {
             label: self.label(),
-            outers: self.place.outers(),
+            outers: outers(&self.place),
             value: Some(value),
             wipe,
             scopes: DeclaredContext::default(),
@@ -263,16 +273,40 @@ fn label(scope: &'static str, identity: &'static str) -> Label {
     })
 }
 
-/// Where a marked field sits: [`Root`] for a field of the record a marker
-/// was emitted for, [`Nested`] for one reached through a record field.
-/// Sealed: [`Marker::field`] makes the one, the derive the other.
+/// The labels of the record fields that hold a field at `place`,
+/// outermost first: empty for a field of the record itself.
+fn outers(place: &impl Place) -> Vec<Label> {
+    let mut outers = Vec::new();
+    place.push_outers(&mut outers);
+    outers
+}
+
+/// The scope a record lists for its own caller, where the record is the
+/// type of another record's field: [`NoScope`] alone. A query of a field of
+/// a record with its own scope would take that scope and the outer
+/// record's.
+#[diagnostic::on_unimplemented(
+    message = "`field` takes a marker of a record that lists no scope of its own, not `{Self}`",
+    label = "a query of this field would take two scopes",
+    note = "the inner record's fields are reached by `field` only when the inner record has no `scope(..)` of its own, stored or supplied"
+)]
+pub trait NestedScope: nested_sealed::Sealed {}
+mod nested_sealed {
+    pub trait Sealed {}
+}
+impl nested_sealed::Sealed for NoScope {}
+impl NestedScope for NoScope {}
+
+/// Where a marked field sits: [`Root`] for a field of the record the
+/// derive emitted the marker for, [`Nested`] for one that
+/// [`Marker::field`] reached through a record field. Sealed.
 pub trait Place: Copy + place_sealed::Sealed {
     /// The outermost record's contexts, narrowed to the record that holds
     /// the field.
     fn narrow(&self, contexts: Contexts) -> Contexts;
-    /// The labels of the record fields that hold the field, outermost
-    /// first: empty for a field of the record itself.
-    fn outers(&self) -> Vec<Label>;
+    /// Push the labels of the record fields that hold the field, outermost
+    /// first: none for a field of the record itself.
+    fn push_outers(&self, outers: &mut Vec<Label>);
 }
 mod place_sealed {
     pub trait Sealed {}
@@ -292,9 +326,7 @@ impl<R> Place for Root<R> {
     fn narrow(&self, contexts: Contexts) -> Contexts {
         contexts
     }
-    fn outers(&self) -> Vec<Label> {
-        Vec::new()
-    }
+    fn push_outers(&self, _: &mut Vec<Label>) {}
 }
 
 /// A field of a record that is itself the field named here, which sits at
@@ -311,38 +343,37 @@ impl<W: Place> Place for Nested<W> {
     fn narrow(&self, contexts: Contexts) -> Contexts {
         self.outer.narrow(contexts).narrowed(self.name)
     }
-    fn outers(&self) -> Vec<Label> {
-        let mut outers = self.outer.outers();
+    fn push_outers(&self, outers: &mut Vec<Label>) {
+        self.outer.push_outers(outers);
         outers.push(label(self.scope, self.identity));
-        outers
     }
 }
 
 /// The type a marker's queries take: [`TakesAny`], any type the field's
 /// index accepts, or [`Takes<V>`], `V` alone. A field marked
-/// `#[stash(query = V)]` is `Takes<V>`.
-#[diagnostic::on_unimplemented(
-    message = "this field's queries take `{Self}`, not `{V}`",
-    label = "a query of another type matches nothing",
-    note = "the record states the field's query type with `#[stash(query = ..)]`"
-)]
-pub trait QueryValue<V>: value_sealed::Sealed {}
+/// `#[stash(query = V)]` is `Takes<V>`. Sealed, for every `V`.
+pub trait QueryValue<V>: value_sealed::Sealed<V> {}
 mod value_sealed {
-    pub trait Sealed {}
+    pub trait Sealed<V> {}
 }
 
 /// A marker whose queries take any type the field's index accepts: the
 /// default, where the record does not state the field's query type.
 #[derive(Debug)]
 pub enum TakesAny {}
-impl value_sealed::Sealed for TakesAny {}
+impl<V> value_sealed::Sealed<V> for TakesAny {}
 impl<V> QueryValue<V> for TakesAny {}
 
 /// A marker whose queries take `V` alone: a field marked
 /// `#[stash(query = V)]`. A query value is copied from its borrowed form,
 /// so a marker of `Takes<String>` accepts `"ada"` as well as a `&String`.
+///
+/// A value of another type is refused at compile time. Since `V` is the one
+/// type the marker accepts, the compiler reports it as a mismatch of the
+/// value's owned form: "type mismatch resolving `<u64 as ToOwned>::Owned
+/// == String`".
 pub struct Takes<V>(PhantomData<fn() -> V>);
-impl<V> value_sealed::Sealed for Takes<V> {}
+impl<V> value_sealed::Sealed<V> for Takes<V> {}
 impl<V> QueryValue<V> for Takes<V> {}
 
 /// A plaintext field whose queries take `V`: `V` itself, or `Option<V>`

packages/stack-encrypt/src/op/mod.rs

@@ -969,7 +969,8 @@ pub trait Answers<Op: Operator, In: Input<Op::Arity>> {
 /// Implementing it is a claim about the stored values: a query term derived
 /// under the label equals the stored term only if the stored term was
 /// derived under the same context. This crate's term targets
-/// ([`EqualityTerm`], [`MatchTerms`], [`OreTerm`], [`OpeTerm`], and
+/// ([`EqualityTerm`], [`MatchTerms`], [`OreTerm`], [`OpeTerm`],
+/// [`OreBlockTerm`], a tuple of them, an `Option` of one, and
 /// [`Encrypted`](crate::target::Encrypted) or a ciphertext beside one
 /// term) are sealed under the caller's context, which is the label. An EQL
 /// v4 type is sealed under the column it stores, which a two-segment label
@@ -993,6 +994,7 @@ impl LabelledTarget for EqualityTerm {}
 impl<O> LabelledTarget for MatchTerms<O> {}
 impl<S: Orderable> LabelledTarget for OreTerm<S> {}
 impl<S: Orderable> LabelledTarget for OpeTerm<S> {}
+impl<S: Orderable> LabelledTarget for OreBlockTerm<S> {}
 impl<T: LabelledTarget> LabelledTarget for (crate::StackCipherText, T) {}
 /// As the terms beside it are: a ciphertext is sealed under the caller's
 /// context, so the terms decide whether the label names theirs.
@@ -1033,6 +1035,12 @@ impl<Op: Operator, In: Input<Op::Arity>, T: Answers<Op, In>> Answers<Op, In>
 /// A nullable field answers what a present value answers. A `None` is a
 /// database NULL, with no term, which no query matches; a `Some` holds
 /// the terms a bare value of `T` holds, derived under the same context.
+///
+/// The input is a present value's. An equality index also accepts an
+/// `Option`, so a query of `None` compiles where the input is not fixed,
+/// and derives a term that no stored row holds: it is not `IS NULL`. A
+/// field marked `#[stash(query = String)]` takes a `String` alone, and
+/// refuses `None`.
 impl<Op: Operator, In: Input<Op::Arity>, T: Answers<Op, In>> Answers<Op, In> for Option<T> {
     type Via = T::Via;
 }
@@ -1059,7 +1067,9 @@ impl<T: LabelledTarget> LabelledTarget for Option<T> {}
 /// Implemented for this crate's terms and the operators [`Eq`](struct@Eq),
 /// [`Lt`], [`Lte`], [`Gt`], [`Gte`], [`Between`] and
 /// [`Matches`](struct@Matches). A term defined in another crate implements
-/// it for each of those to sit in a tuple.
+/// it for each of those to sit in a tuple, and implements
+/// [`LabelledTarget`] too: a tuple is queried only when each of its terms
+/// was derived under the field's label.
 #[diagnostic::on_unimplemented(
     message = "`{Self}` does not say whether it answers `{Op}`",
     label = "a term in a tuple of terms states its answer to each operator",