docs(stack-encrypt): say what is transitional and what the engine does not call

Three places where the docs promised more than the code does.

An indexed plan field without "type" is still dispatched on each value's
own tag, so for that field the engine trusts the binding's tagging: a 34
sent once as a Float64 and once as an Int64 under one "ore" field stores
two different terms. That keeps the Go binding's current plans valid, and
it is meant to end once that binding fills "type" from its struct types.
The plan() rustdoc, FieldPlan and the dynamic module docs now say so, and
point at #1082, which tracks making "type" required on every field with a
term output.

dynamic::read is the whole query-side type story, and nothing in the
engine calls it: term() takes a Scalar and an IndexSpec and never sees
the field's declared kind. Its rustdoc now says that plainly, that a
binding deriving a query term for a typed field must call it first, and
that wiring it into query(v).using(&plan) is tracked in #1057.

Indexes::select said generic code over X: Indexes<S> can call
indexes.select::<Ore, _>(), which does not compile without a Select
bound. The sentence is replaced by a doctest that shows the bound, and
the method's position parameter is renamed At -> P, so the rendered
signature no longer reads as if it named the At<N> struct.

Author: coderdan

packages/stack-encrypt/src/dynamic/kind.rs

@@ -25,12 +25,16 @@
 //!   plan is built), and refuses a value of any other kind (when it runs),
 //!   so the term bytes are the declared kind's and no binding is trusted to
 //!   have tagged the value right;
-//! - **query** reads the query value *as* the field's kind ([`read`]): `34`
-//!   against a `uint64` field is the `u64` term, whatever number type the
-//!   host handed over;
+//! - **query** is meant to read the query value *as* the field's kind
+//!   ([`read`]): `34` against a `uint64` field is the `u64` term, whatever
+//!   number type the host handed over. The engine does not do this for the
+//!   caller yet; see [`read`];
 //! - **decrypt** refuses an opened value of any other kind, so a host with no
 //!   types of its own can rely on the declaration for what it gets back (an
 //!   integer, not a float; bytes, not a string).
+//!
+//! A field with no `"type"` is dispatched on each value's own tag. That is
+//! transitional; see [`record::plan`](super::record::plan()).
 use vitaminc_aead_value::{FfiValue, ValueKind};
 
 use super::Error;
@@ -76,6 +80,15 @@ pub fn admits(kind: ValueKind, index: &IndexSpec) -> bool {
 /// being sealed is not converted; it must already be of the field's kind,
 /// and is refused otherwise.
 ///
+/// **The engine does not call this.** [`term`](super::term()) takes a
+/// [`Scalar`](super::Scalar) and an [`IndexSpec`] and never sees the field's
+/// declared kind, so a binding deriving a query term for a typed field must
+/// call `read` first, with [`FieldPlan::field_type`](super::FieldPlan::field_type).
+/// One that skips it hands `Float64(34.0)` to a `uint64` field, derives a
+/// float term where the stored one is the `u64` term, and matches nothing,
+/// with no error. Wiring this into the plan's query path
+/// (`query(v).using(&plan)`) is tracked in #1057.
+///
 /// ```
 /// use stack_encrypt::dynamic::{read, FfiValue, ValueKind};
 ///

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

@@ -46,7 +46,9 @@
 //! the type it was sealed as. They are not this crate's: a declared type is
 //! vitaminc's [`ValueKind`], re-exported here, whose names vitaminc freezes
 //! beside its tag table. This crate adds only what a kind means to an index
-//! ([`admits`]) and to a query value ([`read`]).
+//! ([`admits`]) and to a query value ([`read`]). A field without `"type"` is
+//! dispatched on each value's own tag; that is transitional, and
+//! [`record::plan`] says until when.
 //!
 //! For the same reason the enums that spell them — [`Output`],
 //! [`IndexSpec`] and [`ValueKind`] — are *not* `#[non_exhaustive]`, against this workspace's

packages/stack-encrypt/src/dynamic/record.rs

@@ -116,7 +116,8 @@ impl Output {
 /// (checked per value), so the engine verifies what a binding hands it
 /// rather than trusting the binding's tagging. A field with no declared type
 /// is dispatched on each value's own type, as every field was before types
-/// existed; that keeps the plans existing bindings send valid.
+/// existed; that keeps the plans existing bindings send valid, and is
+/// transitional (see [`plan`]).
 #[derive(Clone, Debug)]
 pub struct FieldPlan {
     name: String,
@@ -296,7 +297,16 @@ impl Plan {
 /// …; see [`ValueKind::name`]): vitaminc's vocabulary, not one of this
 /// crate's. Declared, it is checked against the field's outputs here
 /// ([`admits`]) and against every value sealed into or opened
-/// from the field; absent, each value is dispatched on its own type.
+/// from the field.
+///
+/// **An indexed field without `"type"` is dispatched on each value's own
+/// tag**, so for that field the engine trusts the binding to tag every value
+/// the same way: a `34` sent once as a `Float64` and once as an `Int64` under
+/// one `"ore"` field is accepted both times and stores two different terms.
+/// This is transitional. It keeps the plans the Go binding sends today, which
+/// carry no `"type"`, valid until that binding fills `"type"` from its struct
+/// types; then `"type"` becomes required on every field with a term output
+/// (#1082).
 ///
 /// `<context>` is defined once, in [`super::context`](super::context()): a
 /// string, bytes, an integer, or a list of those, with what each spells in

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

@@ -288,13 +288,13 @@ pub trait Indexes<S> {
     /// query asks one index for one term and needs no ciphertext; its
     /// [`operation`](Index::operation) is that term alone.
     ///
-    /// `At` is where `I` sits and is inferred; leave it `_`. Asking for an
-    /// index the set does not hold does not compile, and neither does asking
-    /// for one the set holds twice, since its place is then ambiguous.
+    /// `P` is where `I` sits (the position [`Select`] names) and is inferred;
+    /// leave it `_`. Asking for an index the set does not hold does not
+    /// compile, and neither does asking for one the set holds twice, since
+    /// its place is then ambiguous.
     ///
-    /// In code generic over `X: Indexes<S>`, as the plan builder is, this is
-    /// `indexes.select::<Ore, _>()`. A concrete tuple is a set of indexes
-    /// over many plaintexts, so there the plaintext is named:
+    /// A concrete tuple is a set of indexes over many plaintexts, so there
+    /// the plaintext is named:
     ///
     /// ```
     /// use stack_encrypt::target::{Equality, Index, IndexSpec, Indexes, Ore};
@@ -303,9 +303,25 @@ pub trait Indexes<S> {
     /// let ore = Indexes::<u32>::select::<Ore, _>(&indexes);
     /// assert_eq!(Index::<u32>::spec(ore), IndexSpec::Ore);
     /// ```
-    fn select<I: Index<S>, At>(&self) -> &I
+    ///
+    /// In code generic over the set, the position is a type parameter too,
+    /// and the set must be bounded by [`Select`] for it: `X: Indexes<S>`
+    /// alone does not let the call compile.
+    ///
+    /// ```
+    /// use stack_encrypt::target::{Equality, Index, IndexSpec, Indexes, Ore, Select};
+    ///
+    /// fn ore_spec<X, P>(indexes: &X) -> IndexSpec
+    /// where
+    ///     X: Indexes<u32> + Select<Ore, P>,
+    /// {
+    ///     Index::<u32>::spec(indexes.select::<Ore, P>())
+    /// }
+    /// assert_eq!(ore_spec(&(Equality, Ore)), IndexSpec::Ore);
+    /// ```
+    fn select<I: Index<S>, P>(&self) -> &I
     where
-        Self: Select<I, At>,
+        Self: Select<I, P>,
     {
         Select::get(self)
     }