refactor(swift): keep the engine out of the public API

The IVM operators, wire-protocol bodies, B-tree, hashes, and JSON
machinery were public, so apps (and the docs) saw ~1,700 symbols. They
are package now: the package's tests, ZeroTesting, and the benchmarks
still see them; apps see what they and the generated code use (~720).

ErroredQuery and escapeLike stay public (views report the one; zbugs
uses the other). zbugs reads JWT claims with JSONDecoder instead of the
engine's parser.

A package type with @inlinable members has to be @usableFromInline, or
other modules quietly get unspecialized calls: BTreeSet<Int> scans from
the benchmarks were 5x slower until it was.

Amp-Thread-ID: https://ampcode.com/threads/T-c513a037-a257-45e0-b9a9-15c15edfe859
Co-authored-by: tmm <tmm@tmm.dev>

Author: ampagent

apps/zbugs-swift/Sources/ZBugs/Auth.swift

@@ -1,3 +1,4 @@
+import Foundation
 import Zero
 
 /// Who the client acts for: the `sub` and `role` of the zbugs JWT
@@ -97,7 +98,7 @@ extension AuthData {
   public init?(jwt: String, now: Double) {
     let parts = jwt.split(separator: ".", omittingEmptySubsequences: false)
     guard parts.count == 3, let payload = base64URLDecode(parts[1]),
-      let claims = try? JSONParser.parse(payload),
+      let claims = try? JSONDecoder().decode(JSONValue.self, from: Data(payload)),
       let sub = claims["sub"]?.stringValue,
       let role = claims["role"]?.stringValue.flatMap(UserRole.init(rawValue:))
     else { return nil }

swift/DESIGN.md

@@ -74,6 +74,11 @@ apps/zbugs-swift/           dogfood app (iOS + macOS)
   in this public monorepo either way.
 - SwiftPM products: `Zero`, `ZeroUI`, `ZeroTesting`, and `ZeroNIOTesting`
   (test-only; the only product that depends on SwiftNIO).
+- The public API is what apps and the generated code use. The engine (IVM
+  operators, the wire protocol, the B-tree, hashes) is `package`: the
+  package's own modules (tests, `ZeroTesting`, benchmarks) see it, apps don't.
+  A `package` type with `@inlinable` members must itself be
+  `@usableFromInline`, or other modules silently get unspecialized calls.
 - The CLI ships as the unscoped npm package `zero-swift` (we don't own the
   `@rocicorp` scope) with a peer dependency on `@rocicorp/zero`. It is
   versioned with the Swift releases.

swift/Sources/Zero/AST/ASTCoding.swift

@@ -1,6 +1,6 @@
 /// JSON encoding of the AST, following `astSchema`.
 extension AST: JSONCodable {
-  public init(json: JSONValue) throws(DecodingError) {
+  package init(json: JSONValue) throws(DecodingError) {
     let r = try JSONObjectReader(json, "AST")
     schema = try r.optionalString("schema")
     table = try r.string("table")
@@ -25,7 +25,7 @@ extension AST: JSONCodable {
     }
   }
 
-  public var json: JSONValue {
+  package var json: JSONValue {
     var o = JSONObjectBuilder()
     o.set("schema", schema)
     o.set("table", .string(table))
@@ -46,7 +46,7 @@ extension AST: JSONCodable {
 }
 
 extension AST.CorrelatedSubquery: JSONCodable {
-  public init(json: JSONValue) throws(DecodingError) {
+  package init(json: JSONValue) throws(DecodingError) {
     let r = try JSONObjectReader(json, "correlated subquery")
     correlation = try r.required("correlation") { (v) throws(DecodingError) in
       let c = try JSONObjectReader(v, "correlation")
@@ -65,7 +65,7 @@ extension AST.CorrelatedSubquery: JSONCodable {
     hidden = try r.optionalBool("hidden")
   }
 
-  public var json: JSONValue {
+  package var json: JSONValue {
     var o = JSONObjectBuilder()
     o.set(
       "correlation",
@@ -80,7 +80,7 @@ extension AST.CorrelatedSubquery: JSONCodable {
 }
 
 extension AST.ValuePosition: JSONCodable {
-  public init(json: JSONValue) throws(DecodingError) {
+  package init(json: JSONValue) throws(DecodingError) {
     let r = try JSONObjectReader(json, "value position")
     let type = try r.string("type")
     switch type {
@@ -120,7 +120,7 @@ extension AST.ValuePosition: JSONCodable {
     }
   }
 
-  public var json: JSONValue {
+  package var json: JSONValue {
     switch self {
     case .literal(let v): ["type": "literal", "value": v]
     case .column(let name): ["type": "column", "name": .string(name)]
@@ -131,7 +131,7 @@ extension AST.ValuePosition: JSONCodable {
 }
 
 extension AST.Condition: JSONCodable {
-  public init(json: JSONValue) throws(DecodingError) {
+  package init(json: JSONValue) throws(DecodingError) {
     let r = try JSONObjectReader(json, "condition")
     let type = try r.string("type")
     switch type {
@@ -166,7 +166,7 @@ extension AST.Condition: JSONCodable {
     }
   }
 
-  public var json: JSONValue {
+  package var json: JSONValue {
     switch self {
     case .simple(let op, let left, let right):
       return ["type": "simple", "op": .string(op.rawValue), "left": left.json, "right": right.json]

swift/Sources/Zero/AST/ASTNormalize.swift

@@ -2,7 +2,7 @@
 /// `related` sorted by alias, `where` flattened and sorted. Two ASTs that
 /// describe the same query hash the same once normalized.
 extension AST {
-  public func normalized() -> AST {
+  package func normalized() -> AST {
     var ast = self
     ast.where = `where`.map { Self.normalizeSubqueries($0) }.map(Self.normalizeCondition)
     if let related {
@@ -37,7 +37,7 @@ extension AST {
     return related
   }
 
-  public static func normalizeCondition(_ cond: Condition) -> Condition {
+  package static func normalizeCondition(_ cond: Condition) -> Condition {
     switch cond {
     case .simple, .correlatedSubquery:
       return cond

swift/Sources/Zero/Builder/Builder.swift

@@ -1,6 +1,6 @@
 /// Connects a pipeline being built to its environment
 /// (`BuilderDelegate` in `packages/zql/src/builder/builder.ts`).
-public protocol BuilderDelegate: AnyObject {
+package protocol BuilderDelegate: AnyObject {
   /// Apply `where` filters even when the source applies them all.
   var applyFiltersAnyway: Bool { get }
   /// Allow NOT EXISTS. Only the server does: a client cannot tell a row
@@ -18,16 +18,16 @@ public protocol BuilderDelegate: AnyObject {
 }
 
 extension BuilderDelegate {
-  public var applyFiltersAnyway: Bool { false }
-  public var enableNotExists: Bool { false }
-  public var disableCorrelatedPredicatePushdown: Bool { false }
-  public func decorateInput(_ input: any Input, name: String) -> any Input { input }
-  public func addEdge(_ source: any InputBase, _ dest: any InputBase) {}
-  public func decorateFilterInput(_ input: any FilterInput, name: String) -> any FilterInput {
+  package var applyFiltersAnyway: Bool { false }
+  package var enableNotExists: Bool { false }
+  package var disableCorrelatedPredicatePushdown: Bool { false }
+  package func decorateInput(_ input: any Input, name: String) -> any Input { input }
+  package func addEdge(_ source: any InputBase, _ dest: any InputBase) {}
+  package func decorateFilterInput(_ input: any FilterInput, name: String) -> any FilterInput {
     input
   }
-  public func decorateSourceInput(_ input: any SourceInput, queryID: String) -> any Input { input }
-  public func mapAst(_ ast: AST) -> AST { ast }
+  package func decorateSourceInput(_ input: any SourceInput, queryID: String) -> any Input { input }
+  package func mapAst(_ ast: AST) -> AST { ast }
 }
 
 /// The limit put on EXISTS subqueries: one row is enough, a few more keep
@@ -36,7 +36,7 @@ let existsLimit = 3
 let permissionsExistsLimit = 1
 
 /// Builds a pipeline from an AST (`buildPipeline`).
-public func buildPipeline(
+package func buildPipeline(
   _ ast: AST, _ delegate: any BuilderDelegate, queryID: String
 )
   throws(PipelineError) -> any Input
@@ -55,18 +55,18 @@ public func buildPipeline(
 }
 
 /// Values for static parameters (`StaticQueryParameters`).
-public struct StaticQueryParameters {
-  public var authData: [String: JSONValue]?
-  public var preMutationRow: Row?
+package struct StaticQueryParameters {
+  package var authData: [String: JSONValue]?
+  package var preMutationRow: Row?
 
-  public init(authData: [String: JSONValue]?, preMutationRow: Row? = nil) {
+  package init(authData: [String: JSONValue]?, preMutationRow: Row? = nil) {
     self.authData = authData
     self.preMutationRow = preMutationRow
   }
 }
 
 /// `bindStaticParameters`: replaces static parameters with their values.
-public func bindStaticParameters(_ ast: AST, _ params: StaticQueryParameters?) -> AST {
+package func bindStaticParameters(_ ast: AST, _ params: StaticQueryParameters?) -> AST {
   func bindValue(_ v: AST.ValuePosition) -> AST.ValuePosition {
     guard case .static(let anchor, let field) = v else { return v }
     guard let params else { preconditionFailure("Static query params do not exist") }

swift/Sources/Zero/Client/ConnectionError.swift

@@ -1,6 +1,6 @@
 /// The kinds of error the client raises itself
 /// (`packages/zero-client/src/client/client-error-kind-enum.ts`).
-public enum ClientErrorKind: String, Sendable, Hashable, CaseIterable {
+package enum ClientErrorKind: String, Sendable, Hashable, CaseIterable {
   case abruptClose = "AbruptClose"
   case cleanClose = "CleanClose"
   case clientClosed = "ClientClosed"
@@ -19,26 +19,26 @@ public enum ClientErrorKind: String, Sendable, Hashable, CaseIterable {
 /// Why a connection ended or could not be made: an error the client raised
 /// (`ClientError`) or one the server sent (`ProtocolError`), together
 /// `ZeroError` in `packages/zero-client/src/client/error.ts`.
-public enum ConnectionError: Error, Sendable, Hashable, CustomStringConvertible {
+package enum ConnectionError: Error, Sendable, Hashable, CustomStringConvertible {
   case client(ClientErrorKind, message: String)
   case server(ErrorBody)
 
-  public var message: String {
+  package var message: String {
     switch self {
     case .client(_, let message): message
     case .server(let body): body.message
     }
   }
 
   /// The kind's name, a `ClientErrorKind` or an `ErrorKind`.
-  public var kindName: String {
+  package var kindName: String {
     switch self {
     case .client(let kind, _): kind.rawValue
     case .server(let body): body.kind.rawValue
     }
   }
 
-  public var description: String { "\(kindName): \(message)" }
+  package var description: String { "\(kindName): \(message)" }
 
   var clientKind: ClientErrorKind? {
     if case .client(let kind, _) = self { return kind }

swift/Sources/Zero/Client/ConnectionManager.swift

@@ -313,7 +313,7 @@ public enum ConnectionState: Sendable, Hashable {
   }
 
   /// The JSON form of the JS `ConnectionState`.
-  public var json: JSONValue {
+  package var json: JSONValue {
     var o: [String: JSONValue] = ["name": .string(status.rawValue)]
     switch self {
     case .initializing, .connected: break
@@ -353,7 +353,7 @@ public enum NeedsAuthReason: Sendable, Hashable {
     self = .zeroCache(reason: error.message)
   }
 
-  public var json: JSONValue {
+  package var json: JSONValue {
     switch self {
     case .mutate(let status, let body), .query(let status, let body):
       var o: [String: JSONValue] = [

swift/Sources/Zero/Client/Definitions.swift

@@ -271,7 +271,7 @@ public enum MutationOutcome: Sendable, Hashable {
   case zeroError(message: String)
 
   /// The JS result object.
-  public var json: JSONValue {
+  package var json: JSONValue {
     switch self {
     case .success(let data):
       var o: [String: JSONValue] = ["type": "success"]

swift/Sources/Zero/Client/Engine.swift

@@ -62,7 +62,7 @@ public struct UpdateNeededReason: Sendable, Hashable {
   public var type: String
   public var message: String?
 
-  public var json: JSONValue {
+  package var json: JSONValue {
     var o: [String: JSONValue] = ["type": .string(type)]
     if let message { o["message"] = .string(message) }
     return .object(o)

swift/Sources/Zero/Client/Keys.swift

@@ -1,22 +1,22 @@
 /// Storage key layout (`packages/zero-client/src/client/keys.ts`).
-public enum Keys {
-  public static let desiredQueriesPrefix = "d/"
-  public static let gotQueriesPrefix = "g/"
-  public static let entitiesPrefix = "e/"
-  public static let mutationsPrefix = "m/"
+package enum Keys {
+  package static let desiredQueriesPrefix = "d/"
+  package static let gotQueriesPrefix = "g/"
+  package static let entitiesPrefix = "e/"
+  package static let mutationsPrefix = "m/"
 
-  public struct InvalidPrimaryKeyValue: Error, CustomStringConvertible {
-    public let column: String
-    public let value: JSONValue?
-    public var description: String {
+  package struct InvalidPrimaryKeyValue: Error, CustomStringConvertible {
+    package let column: String
+    package let value: JSONValue?
+    package var description: String {
       "Invalid primary key value for \(column): \(value.map(JSONSerializer.stringify) ?? "undefined")"
     }
   }
 
   /// `toPrimaryKeyString`: `e/<table>/<id>`. A single-column key is the value
   /// as JS `String()` prints it; a compound key is the decimal `h128` of the
   /// JSON array of its values.
-  public static func primaryKeyString(
+  package static func primaryKeyString(
     table: String, primaryKey: [String], row: Row
   ) throws(InvalidPrimaryKeyValue) -> String {
     func scalar(_ column: String) throws(InvalidPrimaryKeyValue) -> JSONValue {
@@ -47,15 +47,15 @@ public enum Keys {
     }
   }
 
-  public static func desiredQueriesKey(clientID: String, hash: String) -> String {
+  package static func desiredQueriesKey(clientID: String, hash: String) -> String {
     desiredQueriesPrefix + clientID + "/" + hash
   }
 
-  public static func gotQueriesKey(hash: String) -> String {
+  package static func gotQueriesKey(hash: String) -> String {
     gotQueriesPrefix + hash
   }
 
-  public static func mutationResponseKey(clientID: String, id: Double) -> String {
+  package static func mutationResponseKey(clientID: String, id: Double) -> String {
     mutationsPrefix + clientID + "/" + JSNumber.format(id)
   }
 }