feat(stack-encrypt): let a target sealed under its own context opt in to queries on its plan

A typed plan answers an operator through its target type's `op::Answers`
impl, but the chain required `Typed<T>: ValueShape<S>`: a label that
converts into `T`'s context. An EQL v4 type is sealed under its column
(`NonEmpty<Identifier>`), so no plan for one could be queried, and
eql-bindings had nowhere to implement `Answers` (#1238).

`op::LabelledTarget` is the opt-in: a target type says its stored terms
were derived under the context a plan's label names. For such a type,
`Chooses` asks only `ValueLayout<S>` (the indexes `T` declares), since a
query derives through the index and never runs `T`'s encryption. Every
other type keeps needing `ValueShape`, so a type sealed under, say, a
tenant id cannot be queried under a label that would match nothing.
This crate's term targets implement the trait, which keeps every query
that compiled before compiling. `Chooses` now resolves the plan itself
(`choose`) rather than through `Resolves`, which keeps `ValueShape`: a
named index (`.via(..)`) on a plan whose type only opts in would send a
term the type does not send.

An EQL query value stores the column it queries, so its index needs the
context its terms were derived under, and must refuse one it cannot
record. `QueryToken`, which only the chain makes, now carries the label
and whether the call extended it (`label`, `is_extended`): with
`.extend(..)` the terms are derived under the label and the extension, so
a term that records the label alone would match nothing. The defaulted
`Supports::check_label` refuses such a context, and the chain runs it in
`check`, where the label is resolved, before any keyset is loaded or term
derived (and again in `prepare`, as for `check`). `Supports::query` stays
infallible: the chain calls it only after `check_label` accepted the
token's context. Every index here takes any context.

Tests: a labelled target is queried under the plan's or the call's label,
and its term reads whether the call extended it; a label its index
refuses loads no keyset; and a UI case pins that a type with an `Answers`
impl but no `LabelledTarget` answers no query on its plan.

Author: coderdan

packages/stack-encrypt/CHANGELOG.md

@@ -29,6 +29,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   whole integer into a decimal at scale 0). `tests/value_kinds.rs` and its
   fixture hold the record path, the data query path and the typed path to
   the same bytes, and the Go SDK reads the fixture too.
+- **A target sealed under a context of its own can opt in to queries on
+  its plan** (#1238). `op::LabelledTarget` says a target type's stored terms
+  were derived under the context a plan's label names. A typed plan for such
+  a type (`Plan::value::<S>().encrypt_into::<T>()`) answers the operators its
+  `op::Answers` impls name, and needs only the indexes `T` declares, not a
+  context the label converts into: an EQL v4 type, sealed under its column,
+  is queried through its plan though it cannot be encrypted through it.
+  This crate's term targets implement it; a type sealed under a context no
+  label names must not, and its plan answers no query. Naming an index with
+  `.via(..)` still needs a type sealed under the label itself.
+  `op::QueryToken` carries the context the query's terms were derived under
+  (`label`, `is_extended`), for a query term that records it, and
+  `op::Supports::check_label` (defaulted to `Ok`) lets such an index refuse
+  a context it cannot record when the query is awaited, before any keyset
+  is resolved or term derived.
 - **A binding queries by operator** (`dynamic` feature; ADR-0009, ADR-0007
   amended 2026-10-16). `dynamic::query_term(keyset, &plan, field, op,
   input, &resolver)` derives the query term for a field of a data plan, an

packages/stack-encrypt/docs/adr/0009-operators-select-the-index-and-a-query-term-is-not-the-stored-term.md

@@ -157,7 +157,11 @@ pub trait Supports<Op: Operator, In: Input<Op::Arity>>: Index<In::Plaintext> {
 `query` makes it from the verifier and the terms the index derived for the
 query's input. `QueryToken` can be made only inside the crate, so only a
 query chain calls `query`, and no caller can turn a stored term into a query
-term by hand.
+term by hand. The token also carries the context the terms were derived
+under, for a query term that records it, as an EQL query value stores its
+column; such an index refuses a context it cannot record in a defaulted
+`check_label`, which the chain runs with `check`, before any term exists
+(#1238).
 
 `QueryTerm` and the two traits that refine it are defined in decision 4.
 `Query` is not `Term`. An ORE index's `Supports<Lt, S>::Query` is the left

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

@@ -661,27 +661,65 @@ pub trait Supports<Op: Operator, In: Input<Op::Arity>>: Index<In::Plaintext> {
         self.check(input)?;
         Ok(self.verifier(input))
     }
+    /// Why this index cannot answer a query whose terms are derived under
+    /// `label`, the plan's or the call's, extended by parts the call gave
+    /// (`.extend(..)`) when `extended` is true: for an index whose query term
+    /// records the context it was derived under, a context it cannot record.
+    /// An EQL query value stores the column it queries, so its index refuses
+    /// a label that names no column, and any extension, which the column
+    /// cannot hold. Run when the query is awaited, before [`check`](Self::check)
+    /// and before any keyset is resolved; every index in this crate takes
+    /// any context and returns `Ok(())`.
+    fn check_label(&self, _label: &Label, _extended: bool) -> Result<(), Error> {
+        Ok(())
+    }
     /// The query term, from the verifier and the terms the index derived
     /// for the input's plaintexts. Only a query chain calls this:
     /// `QueryToken` cannot be made outside this crate, so no caller can
     /// pair one query's tokens with another value's filter, or pass a
     /// stored term off as a query.
+    ///
+    /// The token carries the context the terms were derived under
+    /// ([`QueryToken::label`], [`QueryToken::is_extended`]), for a query
+    /// term that records it beside its terms. The chain calls this only
+    /// after [`check_label`](Self::check_label) accepted that context, so a
+    /// term built from it need not refuse it again.
     fn query(
         verifier: Self::Verifier,
         terms: In::Terms<Self::Term>,
         token: QueryToken,
     ) -> Self::Query;
 }
 
-/// Proof that [`Supports::query`] is called by a query chain. Only this
-/// crate can make one, so an index in another crate can implement
-/// [`Supports`] but no caller can turn a term into a query term by hand.
+/// Proof that [`Supports::query`] is called by a query chain, and the
+/// context the query's terms were derived under. Only this crate can make
+/// one, so an index in another crate can implement [`Supports`] but no
+/// caller can turn a term into a query term by hand, or name a context its
+/// terms were not derived under.
 #[derive(Debug)]
-pub struct QueryToken(());
+pub struct QueryToken {
+    label: Label,
+    extended: bool,
+}
 
 impl QueryToken {
-    pub(crate) fn new() -> Self {
-        Self(())
+    pub(crate) fn new(label: Label, extended: bool) -> Self {
+        Self { label, extended }
+    }
+
+    /// The label the query's terms were derived under, before any
+    /// extension: the plan's or the call's, the context the write used for
+    /// the field. It is the whole context exactly when
+    /// [`is_extended`](Self::is_extended) is false.
+    pub fn label(&self) -> &Label {
+        &self.label
+    }
+
+    /// Whether the call extended the label by parts of its own
+    /// (`.extend(..)`), so the terms were derived under the label followed
+    /// by those parts rather than the label alone.
+    pub fn is_extended(&self) -> bool {
+        self.extended
     }
 }
 
@@ -813,6 +851,43 @@ pub trait Answers<Op: Operator, In: Input<Op::Arity>> {
     type Via: Supports<Op, In> + Default;
 }
 
+/// A target type whose stored terms were derived under the context a
+/// query's label names, so a plan for it
+/// (`Plan::value::<S>().encrypt_into::<T>()`) answers the operators its
+/// [`Answers`] impls name, with each query derived under the plan's label.
+///
+/// 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
+/// [`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
+/// names, and its index refuses any other label
+/// ([`Supports::check_label`]). A type sealed under a context no label
+/// names, such as an integer tenant id, must not implement it: a query on
+/// its plan would match nothing, with no error.
+///
+/// A query on such a plan derives through the index alone and never runs
+/// the target's own encryption, so the target need not accept the label as
+/// its context: an EQL type, sealed under a column identifier, cannot be
+/// encrypted through its plan and is queried through it all the same.
+#[diagnostic::on_unimplemented(
+    message = "`{Self}` is not queried under a plan's label",
+    label = "a typed plan for this target type answers no query",
+    note = "a target type answers queries on its plan when it implements `op::LabelledTarget`: its stored terms were derived under the context the plan's label names"
+)]
+pub trait LabelledTarget {}
+
+impl LabelledTarget for EqualityTerm {}
+impl<O> LabelledTarget for MatchTerms<O> {}
+impl<S: CllwOreEncrypt> LabelledTarget for OreTerm<S> {}
+impl<S: CllwOpeEncrypt> LabelledTarget for OpeTerm<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.
+impl<T: LabelledTarget> LabelledTarget for crate::target::Encrypted<T> {}
+
 impl<S: crate::Encrypt + 'static> Answers<Eq, S> for EqualityTerm {
     type Via = Equality;
 }

packages/stack-encrypt/src/plan/chain.rs

@@ -9,9 +9,9 @@ use uuid::Uuid;
 
 use super::build::{FieldPlan, FieldsBuilder, IntoLabel, Opens, PlanContext, Runs};
 use super::field_ref::FieldRef;
-use super::value::{Indexed, Typed, ValuePlan, ValueShape};
+use super::value::{Indexed, Typed, ValueLayout, ValuePlan, ValueShape};
 use super::PlanError;
-use crate::op::{Answers, DefaultIndex, Input, Operator, QueryToken, Supports};
+use crate::op::{Answers, DefaultIndex, Input, LabelledTarget, Operator, QueryToken, Supports};
 use crate::target::{
     ciphertext, Borrowed, CallerContext, DeclaredContext, DecryptField, Decryptable, EncryptFrom,
     Index, Indexes, Pending, PendingFuture, Select, Whole,
@@ -650,7 +650,22 @@ impl<'a, Op: Operator, F: Input<Op::Arity>, K: 'static> QueryBuilder<'a, Op, F,
     where
         P: Chooses<Op, F, At>,
     {
-        self.via(P::Via::default()).on(plan)
+        let QueryBuilder {
+            mut common,
+            value,
+            op,
+        } = self;
+        let (index, label) = match common.call_context() {
+            Ok(call) => plan.choose(call),
+            Err(error) => (P::Via::default(), Err(error)),
+        };
+        QueryOp {
+            common,
+            value,
+            index,
+            label,
+            op,
+        }
     }
 }
 
@@ -711,7 +726,12 @@ where
 ///
 /// A field of a fields plan and a one-value plan built `with` indexes
 /// answer through the operator's [`DefaultIndex`]; a one-value plan for a
-/// target type answers through the type's [`Answers`] impl. The plan's
+/// target type answers through the type's [`Answers`] impl, when the type
+/// is a [`LabelledTarget`], whose stored terms were derived under the
+/// context the plan's label names. Such a plan is queried through the
+/// indexes the type declares ([`ValueLayout`]) even when the type cannot be
+/// encrypted through it, as an EQL type sealed under its column cannot.
+/// The plan's
 /// plaintext is the input's ([`Input::Plaintext`]): `S` for a query given
 /// an `S`, and for a `Between` given an `(S, S)`. `At` is the position of
 /// that index in a plan built `with` several, and is inferred.
@@ -720,15 +740,21 @@ where
     label = "no index answers this operator on this plan",
     note = "a field of a fields plan or a plan built `with` indexes answers an operator through its default index (`op::Eq`: `Equality`; `op::Matches`: `Match` with the default configuration, case-insensitive and over text only; `op::Lt`, `Lte`, `Gt`, `Gte` and `Between`: `Ore` over an integer, `Between` given a pair); a typed plan answers the operators its target type implements `Answers` for; `.via(index)` names an index the plan declares"
 )]
-pub trait Chooses<Op: Operator, In: Input<Op::Arity>, At>:
-    Resolves<In::Plaintext, Self::Via, At>
-{
+pub trait Chooses<Op: Operator, In: Input<Op::Arity>, At>: plan_sealed::Sealed {
     /// The index that answers `Op` on this plan.
     type Via: Supports<Op, In> + Default;
+    /// The index the query runs through on this plan, and the label the
+    /// write used, or why the plan refuses the query, as
+    /// [`Resolves::resolve`] says. `call` is the context the call named, if
+    /// any.
+    fn choose(&self, call: Option<Label>) -> (Self::Via, Result<Label, PlanError>);
 }
 
 impl<Op: DefaultIndex<In>, In: Input<Op::Arity>> Chooses<Op, In, Whole> for FieldPlan {
     type Via = Op::Via;
+    fn choose(&self, call: Option<Label>) -> (Op::Via, Result<Label, PlanError>) {
+        Resolves::<In::Plaintext, Op::Via, Whole>::resolve(self, Op::Via::default(), call)
+    }
 }
 
 impl<Op, S, In, X, At> Chooses<Op, In, At> for ValuePlan<S, Indexed<X>>
@@ -740,18 +766,25 @@ where
     X: Indexes<S> + Select<Op::Via, At>,
 {
     type Via = Op::Via;
+    fn choose(&self, call: Option<Label>) -> (Op::Via, Result<Label, PlanError>) {
+        Resolves::<S, Op::Via, At>::resolve(self, Op::Via::default(), call)
+    }
 }
 
 impl<Op, S, In, T> Chooses<Op, In, Whole> for ValuePlan<S, Typed<T>>
 where
     Op: Operator,
     In: Input<Op::Arity, Plaintext = S>,
     S: 'static,
-    T: Answers<Op, In>,
-    T::Via: Default,
-    Typed<T>: ValueShape<S>,
+    T: Answers<Op, In> + LabelledTarget,
+    Typed<T>: ValueLayout<S>,
 {
     type Via = T::Via;
+    fn choose(&self, call: Option<Label>) -> (T::Via, Result<Label, PlanError>) {
+        let index = T::Via::default();
+        let label = self.query_label(&index.spec(), call);
+        (index, label)
+    }
 }
 
 mod plan_sealed {
@@ -769,7 +802,11 @@ mod plan_sealed {
 /// A field of a fields plan ([`Plan::field`](super::Plan::field)) and a
 /// one-value plan for a target type take the index as given, and refuse
 /// one the plan does not declare when the query is awaited
-/// ([`PlanError::IndexNotDeclared`]). A one-value plan built `with`
+/// ([`PlanError::IndexNotDeclared`]). A one-value plan for a target type
+/// takes a named index only when the type is sealed under the label
+/// ([`ValueShape`]): a type that answers through its [`Answers`] impls
+/// alone, as an EQL type does, cannot have another index named on its
+/// plan, which would send a term the type's SQL does not take. A one-value plan built `with`
 /// indexes selects its own index of that type ([`Indexes::select`]), at
 /// the position `At`, which is inferred; a plan without that index does
 /// not compile.
@@ -841,9 +878,9 @@ where
         self.common.keyset.take()
     }
     fn check(&self) -> Result<(), Error> {
-        if let Err(error) = &self.label {
-            return Err(error.clone().into());
-        }
+        let label = self.label.as_ref().map_err(|error| error.clone())?;
+        self.index
+            .check_label(label, self.common.extend.is_extended())?;
         self.index.check(&self.value)
     }
     fn prepare<'p>(self, keyset: &'p KeysetCipher<'a, K>, _: bool) -> Pending<'p, Self::Output, K>
@@ -855,16 +892,22 @@ where
             Err(error) => return Pending::failed(keyset, error.into()),
         };
         // `check` ran before any keyset was resolved; a chain prepared on
-        // its own is held to the same refusal, so no term is derived from a
-        // value the index refuses. `admit` checks and takes the verifier in
-        // one pass over the value.
-        let verifier = match self.index.admit(&self.value) {
+        // its own is held to the same refusals, so no term is derived under
+        // a context or from a value the index refuses. `admit` checks and
+        // takes the verifier in one pass over the value.
+        let extended = self.common.extend.is_extended();
+        let verifier = match self
+            .index
+            .check_label(&label, extended)
+            .and_then(|()| self.index.admit(&self.value))
+        {
             Ok(verifier) => verifier,
             Err(error) => return Pending::failed(keyset, error),
         };
+        let token = QueryToken::new(label.clone(), extended);
         self.value
             .derive(&self.index, keyset, label, self.common.extend)
-            .map(move |terms| I::query(verifier, terms, QueryToken::new()))
+            .map(move |terms| I::query(verifier, terms, token))
     }
 }
 

packages/stack-encrypt/src/plan/value.rs

@@ -337,6 +337,14 @@ mod sealed {
 /// into that context. A target whose context is, say, a `NonEmpty<u64>`
 /// builds, and runs through
 /// [`encryption_with_context`](ValuePlan::encryption_with_context).
+///
+/// A query through a [`Typed`] plan whose target is a
+/// [`LabelledTarget`](crate::op::LabelledTarget) needs only this: the query
+/// derives through the index the target's `Answers` impl names, under the
+/// plan's label, and never runs the target's encryption. So an EQL type,
+/// sealed under its column rather than the label, is queried through its
+/// plan though it cannot be encrypted through it. Naming another index with
+/// `.via(..)` needs [`ValueShape`].
 pub trait ValueLayout<S>: sealed::Sealed + Clone {
     /// What one run produces.
     type Output: 'static;
@@ -346,7 +354,9 @@ pub trait ValueLayout<S>: sealed::Sealed + Clone {
 
 /// How a one-value plan lays its value out under a [`Label`]: [`Indexed`]
 /// or [`Typed`]. What [`ValuePlan::encryption`], `cipher.encrypt(..).using`
-/// and a query through the plan ask. Sealed.
+/// and a query that names its index with `.via(..)` ask. A query that lets
+/// a [`Typed`] plan choose the index asks only [`ValueLayout`], when the
+/// target is a [`LabelledTarget`](crate::op::LabelledTarget). Sealed.
 pub trait ValueShape<S>: ValueLayout<S> {
     /// The description of one value, run under its whole context.
     fn lower<'s, K: 'static>(&self) -> Encryption<'s, S, Self::Output, K, CallerContext>
@@ -542,10 +552,12 @@ impl<S, X> ValuePlan<S, Indexed<X>> {
 
 impl<S, T> ValuePlan<S, Typed<T>>
 where
-    Typed<T>: ValueShape<S>,
+    Typed<T>: ValueLayout<S>,
 {
     /// The label a query through `index` is derived under, or why the plan
-    /// cannot answer it.
+    /// cannot answer it. It reads only the indexes `T` declares
+    /// ([`ValueLayout`]); which plans may be queried at all is the query
+    /// chain's (`Chooses`, `Resolves`).
     pub(crate) fn query_label(
         &self,
         index: &IndexSpec,

packages/stack-encrypt/src/target/context.rs

@@ -172,6 +172,11 @@ impl<'a, T: IntoContext<'a>> From<NonEmpty<T>> for DeclaredContext {
     }
 }
 impl DeclaredContext {
+    /// Whether any part extends the field's own context.
+    pub(crate) fn is_extended(&self) -> bool {
+        !self.0.is_empty()
+    }
+
     /// Extend by one more part, after any already given: the field's own
     /// context, extended by every part so far, is extended by `part`.
     pub fn with(mut self, part: impl Into<CallerContext>) -> Self {