add subscript labels to pipeline stages, since this is causing so man…

…y mistakes. also move update statements towards functional API

Sources/BSONABI/Fields/BSON.Key.swift

@@ -65,7 +65,7 @@ extension BSON.Key
     ///
     /// Some applications that use BSON, such as MongoDB, consider `.`
     /// characters significant.
-    @available(*, deprecated, message: "Prefer 'Mongo.KeyPath' instead.")
+    @available(*, deprecated, message: "Prefer 'Mongo.AnyKeyPath' instead.")
     @inlinable public static
     func / (self:Self, next:Self) -> Self
     {

Sources/MongoABI/Mongo.KeyPath.swift → Sources/MongoABI/Mongo.AnyKeyPath.swift

@@ -2,8 +2,12 @@ import BSON
 
 extension Mongo
 {
+    @available(*, deprecated, renamed: "AnyKeyPath")
+    public
+    typealias KeyPath = AnyKeyPath
+
     @frozen public
-    struct KeyPath:Equatable, Hashable, Sendable
+    struct AnyKeyPath:Equatable, Hashable, Sendable
     {
         public
         var stem:BSON.Key
@@ -15,34 +19,37 @@ extension Mongo
         }
     }
 }
-extension Mongo.KeyPath
+extension Mongo.AnyKeyPath:RawRepresentable
 {
+    /// See ``rawValue``.
     @inlinable public
     init(rawValue:String)
     {
         self.init(stem: .init(rawValue: rawValue))
     }
 
+    /// The key path stem, which is the entire key path minus the leading `$` character that
+    /// would normally appear when encoding the key path in an expression.
     @inlinable public
     var rawValue:String { self.stem.rawValue }
 }
-extension Mongo.KeyPath:ExpressibleByStringLiteral
+extension Mongo.AnyKeyPath:ExpressibleByStringLiteral
 {
     @inlinable public
     init(stringLiteral:String)
     {
         self.init(rawValue: stringLiteral)
     }
 }
-extension Mongo.KeyPath:CustomStringConvertible
+extension Mongo.AnyKeyPath:CustomStringConvertible
 {
     @inlinable public
     var description:String { "$\(self.stem)" }
 }
-extension Mongo.KeyPath:BSONStringEncodable
+extension Mongo.AnyKeyPath:BSONStringEncodable
 {
 }
-extension Mongo.KeyPath
+extension Mongo.AnyKeyPath
 {
     /// Creates a key path by joining two key paths with a `.` character.
     @inlinable public static

Sources/MongoABI/Mongo.Variable.swift

@@ -18,9 +18,9 @@ extension Mongo
 extension Mongo.Variable where T:MongoMasterCodingModel
 {
     @inlinable public
-    subscript(key:T.CodingKey) -> Mongo.KeyPath
+    subscript(key:T.CodingKey) -> Mongo.AnyKeyPath
     {
-        //  When the key path is encoded, ``Mongo.KeyPath``
+        //  When the key path is encoded, ``Mongo.AnyKeyPath``
         //  will add an additional prefixed dollar sign.
         .init(rawValue: "$\(self.name).\(key.rawValue)")
     }

Sources/MongoABI/MongoMasterCodingModel.swift

@@ -12,7 +12,7 @@ protocol MongoMasterCodingModel<CodingKey>
 extension MongoMasterCodingModel
 {
     @inlinable public static
-    subscript(key:CodingKey) -> Mongo.KeyPath
+    subscript(key:CodingKey) -> Mongo.AnyKeyPath
     {
         .init(rawValue: key.rawValue)
     }

Sources/MongoBuiltins/BSONEncodable (ext).swift

@@ -3,10 +3,10 @@ import BSON
 extension BSONEncodable where Self == Mongo.Expression
 {
     @inlinable public static
-    func expr(with populate:(inout Self) throws -> ()) rethrows -> Self
+    func expr(with populate:(inout Mongo.ExpressionEncoder) throws -> ()) rethrows -> Self
     {
-        var expr:Self = .init(.init())
-        try populate(&expr)
-        return expr
+        var document:BSON.Document = .init()
+        try populate(&document.output[as: Mongo.ExpressionEncoder.self])
+        return .init(document)
     }
 }

Sources/MongoBuiltins/Documents/Bucket/Mongo.BucketOutputDocument.swift

@@ -19,7 +19,7 @@ extension Mongo
 extension Mongo.BucketOutputDocument
 {
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> Mongo.Accumulator?
+    subscript(path:Mongo.AnyKeyPath) -> Mongo.Accumulator?
     {
         get
         {

Sources/MongoBuiltins/Documents/Facet/Mongo.FacetDocument.swift

@@ -19,7 +19,7 @@ extension Mongo
 extension Mongo.FacetDocument
 {
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> Mongo.Pipeline?
+    subscript(path:Mongo.AnyKeyPath) -> Mongo.Pipeline?
     {
         get
         {

Sources/MongoBuiltins/Documents/Group/Mongo.GroupDocument.swift

@@ -19,7 +19,7 @@ extension Mongo
 extension Mongo.GroupDocument
 {
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> Mongo.Accumulator?
+    subscript(path:Mongo.AnyKeyPath) -> Mongo.Accumulator?
     {
         get
         {

Sources/MongoBuiltins/Documents/Let/Mongo.LetDocument.swift

@@ -19,7 +19,7 @@ extension Mongo
 extension Mongo.LetDocument
 {
     @inlinable public
-    subscript<Encodable>(path:Mongo.KeyPath) -> Encodable?
+    subscript<Encodable>(path:Mongo.AnyKeyPath) -> Encodable?
         where Encodable:BSONEncodable
     {
         get

Sources/MongoBuiltins/Documents/Lookup/Mongo.LookupDocument.swift

@@ -19,7 +19,7 @@ extension Mongo
 extension Mongo.LookupDocument
 {
     @inlinable public
-    subscript(key:Field) -> Mongo.KeyPath?
+    subscript(key:Field) -> Mongo.AnyKeyPath?
     {
         get
         {

Sources/MongoBuiltins/Documents/Merge/Mongo.MergeDocument.swift

@@ -44,7 +44,7 @@ extension Mongo.MergeDocument
     }
 
     @inlinable public
-    subscript(key:On) -> Mongo.KeyPath?
+    subscript(key:On) -> Mongo.AnyKeyPath?
     {
         get
         {

Sources/MongoBuiltins/Documents/Mongo.AnyKeyPath (ext).swift

@@ -0,0 +1,5 @@
+import MongoABI
+
+extension Mongo.AnyKeyPath:_MongoExpressionRestrictedEncodable
+{
+}

Sources/MongoBuiltins/Documents/Predicate/Mongo.PredicateDocument.swift

@@ -30,7 +30,7 @@ extension Mongo.PredicateDocument
     /// ``PredicateOperator`` has no subscripts that accept string
     /// literals, so it will never conflict with ``BSON.Document``.
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> Mongo.PredicateOperator?
+    subscript(path:Mongo.AnyKeyPath) -> Mongo.PredicateOperator?
     {
         get
         {
@@ -42,7 +42,7 @@ extension Mongo.PredicateDocument
         }
     }
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> Self?
+    subscript(path:Mongo.AnyKeyPath) -> Self?
     {
         get
         {
@@ -57,7 +57,7 @@ extension Mongo.PredicateDocument
     //  ``_MongoExpressionRestrictedEncodable``-gated diagnostic subscript.
     @_disfavoredOverload
     @inlinable public
-    subscript<Encodable>(path:Mongo.KeyPath) -> Encodable? where Encodable:BSONEncodable
+    subscript<Encodable>(path:Mongo.AnyKeyPath) -> Encodable? where Encodable:BSONEncodable
     {
         get
         {
@@ -76,7 +76,7 @@ extension Mongo.PredicateDocument
         even in a '$match' stage of an aggregation pipeline.
         """)
     public
-    subscript<Expression>(path:Mongo.KeyPath) -> Expression?
+    subscript<Expression>(path:Mongo.AnyKeyPath) -> Expression?
         where Expression:_MongoExpressionRestrictedEncodable
     {
         get

Sources/MongoBuiltins/Documents/Projection/Mongo.ProjectionDocument.swift

@@ -24,7 +24,7 @@ extension Mongo.ProjectionDocument
     /// ``ProjectionOperator`` has no subscripts that accept string
     /// literals, so it will never conflict with ``BSON.Document``.
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> Mongo.ProjectionOperator?
+    subscript(path:Mongo.AnyKeyPath) -> Mongo.ProjectionOperator?
     {
         get
         {
@@ -36,7 +36,7 @@ extension Mongo.ProjectionDocument
         }
     }
     @inlinable public
-    subscript<Encodable>(path:Mongo.KeyPath) -> Encodable? where Encodable:BSONEncodable
+    subscript<Encodable>(path:Mongo.AnyKeyPath) -> Encodable? where Encodable:BSONEncodable
     {
         get
         {

Sources/MongoBuiltins/Documents/Set/Mongo.SetDocument.swift

@@ -19,15 +19,15 @@ extension Mongo
 extension Mongo.SetDocument
 {
     @inlinable public
-    subscript<Encodable>(path:Mongo.KeyPath) -> Encodable? where Encodable:BSONEncodable
+    subscript<Encodable>(path:Mongo.AnyKeyPath) -> Encodable? where Encodable:BSONEncodable
     {
         get
         {
             nil
         }
         set(value)
         {
-            value?.encode(to: &self.bson[with: path.stem])
+            value?.encode(to: &self.bson[with: path])
         }
     }
 }

Sources/MongoBuiltins/Documents/Sort/Mongo.SortDocument.swift

@@ -21,7 +21,7 @@ extension Mongo.SortDocument
     @available(*, unavailable,
         message: "pass the `(+)` or `(-)` operator functions to specify sort direction.")
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> Int?
+    subscript(path:Mongo.AnyKeyPath) -> Int?
     {
         get
         {
@@ -50,7 +50,7 @@ extension Mongo.SortDocument
         }
     }
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> ((Mongo.SortAscending) -> Never)?
+    subscript(path:Mongo.AnyKeyPath) -> ((Mongo.SortAscending) -> Never)?
     {
         get
         {
@@ -81,7 +81,7 @@ extension Mongo.SortDocument
         }
     }
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> ((Mongo.SortDescending) -> Never)?
+    subscript(path:Mongo.AnyKeyPath) -> ((Mongo.SortDescending) -> Never)?
     {
         get
         {
@@ -96,7 +96,7 @@ extension Mongo.SortDocument
         }
     }
     @inlinable public
-    subscript(path:Mongo.KeyPath) -> Mongo.SortOperator?
+    subscript(path:Mongo.AnyKeyPath) -> Mongo.SortOperator?
     {
         get
         {

Sources/MongoBuiltins/Documents/Unwind/Mongo.UnwindDocument.swift

@@ -19,7 +19,7 @@ extension Mongo
 extension Mongo.UnwindDocument
 {
     @inlinable public
-    subscript(key:Field) -> Mongo.KeyPath?
+    subscript(key:Field) -> Mongo.AnyKeyPath?
     {
         get
         {