fix(protocol): treat optional array fields as Path leaves; export predicate types

`Path<T>` synthesized bogus dotted-path keys for OPTIONAL array fields.
The leaf test in `_AllPaths` ran on the raw `T[K]`, which for `tags?:
string[]` is `string[] | undefined`; the `undefined` arm defeats the
`ReadonlyArray` leaf check in `_IsPathLeaf` (a union does not extend
`ReadonlyArray`), so the walker descended into `Array.prototype` and
emitted `` `tags.map.${string}` `` typed `undefined`. Required arrays
were unaffected.

That synthetic `undefined`-typed path broke structural assignability of
a bound `Db<Config>`/`BaerlyClient<Config>` to a hand-rolled interface
whose `collection(name: string)` takes a runtime string: the generic
collapses the row to the union of every row, and the bogus path made any
index-signature predicate object non-assignable — so registering one
unrelated collection with an optional array field broke `.where()`
typing everywhere.

Run the leaf test on `NonNullable<T[K]>` so an optional array terminates
path recursion exactly like a required one. `Path<{ tags?: string[] }>`
is now `"tags"`, with no `Array.prototype` members.

Also export the types consumers needed to avoid hand-rolling a
structural shim in the first place:
- `Predicate` / `PredicateArg` from `@gusto/baerly-storage`
- `PredicateArg` from `@gusto/baerly-storage/client` (which already
  exported `ClientCollection` / `Predicate`). The client handle type
  stays `ClientCollection`; the in-process `Collection` is exported only
  from the root entry, since the client's HTTP handle is structurally
  distinct (read-only `.where(...)`, `TerminalOptions`).

Adds a `Path` regression assertion in collection-api.test-d.ts. Both
changes are additive and type-only; verify:agent, bundle-sizes (all 18
under budget), and the default test suite are green.

Author: baer

.changeset/path-optional-array-leaf.md

@@ -0,0 +1,54 @@
+---
+"@gusto/baerly-storage": minor
+---
+
+Fix `Path<T>` walking `Array.prototype` for optional array fields; export
+`PredicateArg` / `Predicate` / `Collection` for consumers
+
+**Bug fix — optional array fields no longer poison predicate types**
+
+`Path<T>` (the dotted-path key type behind `Predicate<T>` / `.where(...)`)
+descended into `Array.prototype` when a field was an **optional** array. For a
+field `tags?: string[]`, the field type is `string[] | undefined`, and the
+`undefined` arm defeated the array-is-a-leaf check — so the path walker
+recursed into the array's methods and synthesized bogus keys like
+`` `tags.map.${string}` `` typed `undefined`.
+
+Required array fields (`tags: string[]`) were unaffected; only the optional
+form triggered it.
+
+The visible symptom: registering **any** collection with an optional array
+field (e.g. a Zod `z.array(z.string()).optional()`) broke structural
+assignability of a bound `Db<Config>` / `BaerlyClient<Config>` to a hand-rolled
+interface whose `collection(name: string)` takes a runtime string — because the
+generic collapses the row to the union of every row, and the synthetic
+`undefined`-typed prototype path made every index-signature predicate object
+non-assignable. Collections that never touched the array field were still
+affected.
+
+The fix runs the leaf test on `NonNullable<T[K]>`, so an optional array
+terminates path recursion exactly like a required one. `Path<{ tags?: string[]
+}>` is now `"tags"`, with no `Array.prototype` members.
+
+**New public exports**
+
+- `PredicateArg` and `Predicate` are now exported from `@gusto/baerly-storage`.
+- `PredicateArg` is now exported from `@gusto/baerly-storage/client` (which
+  already exported `ClientCollection` and `Predicate`). The client handle type
+  remains `ClientCollection`; the in-process `Collection` type is exported only
+  from the root `@gusto/baerly-storage` entry, since the client's HTTP handle
+  is structurally distinct (read-only `.where(...)`, `TerminalOptions`).
+
+These let consumers name the `.where(...)` argument and predicate types
+directly instead of hand-rolling a structural interface to accept a `Db` or a
+`BaerlyClient`.
+
+**Migration**
+
+- No action required. Both changes are additive; existing typed call sites are
+  unaffected.
+- If you hand-rolled a structural `collection(name: string)` shim to read
+  collections by a runtime-computed name, you can now either import the real
+  types, or narrow at the boundary with
+  `(db as Db<UnboundConfig>).collection(name)` to open the row to
+  `DocumentData` for dynamic names.

packages/client/src/index.ts

@@ -14,4 +14,5 @@ export type {
   LogEntry,
   OrderSpec,
   Predicate,
+  PredicateArg,
 } from "@baerly/protocol";

packages/protocol/src/collection-api.test-d.ts

@@ -19,7 +19,7 @@
  * from any barrel — exporting the assertion handles is harmless.
  */
 
-import { type Predicate } from "./collection-api.ts";
+import { type Path, type Predicate } from "./collection-api.ts";
 import type { PredicateArg, PredicateBuilder } from "./query/builder.ts";
 import type { DocumentData } from "./json.ts";
 
@@ -187,3 +187,28 @@ export const _depth6Rejected: Predicate<DeepDoc> = {
 
 export const _builderReturnsSelf = (q: PredicateBuilder<Ticket>): PredicateBuilder<Ticket> =>
   q.eq("status", "open").gt("count", 5);
+
+// --- Optional array/nested fields are Path leaves (regression) -----
+// An OPTIONAL array field must terminate `Path` recursion the same as a
+// required one. The leaf test in `_AllPaths` runs on `NonNullable<T[K]>`;
+// without that guard, `T["tags"]` was `string[] | undefined`, whose
+// `undefined` arm defeated the `ReadonlyArray` leaf check, so `_AllPaths`
+// descended into `Array.prototype` and synthesized `tags.map.${string}:
+// undefined`. That bogus path broke structural assignability for consumers
+// whose predicate parameter is an index signature (e.g. a hand-rolled
+// `collection(name: string)` shim over a config whose row union contains an
+// optional array field). See the matching changeset.
+type OptArrayDoc = DocumentData & { kind: string; tags?: string[] };
+
+// The optional array field itself is the only path it contributes.
+export const _optArrayIsLeafPath: Path<OptArrayDoc> = "tags";
+export const _optArraySiblingPath: Path<OptArrayDoc> = "kind";
+
+// No `Array.prototype` members leak into `Path<T>`.
+// @ts-expect-error — `tags.map` is Array.prototype, not a document path.
+export const _noArrayPrototypeMap: Path<OptArrayDoc> = "tags.map";
+// @ts-expect-error — nor any deeper synthetic prototype path.
+export const _noArrayPrototypeDeep: Path<OptArrayDoc> = "tags.map.length";
+
+// Predicate-level: the optional array remains a queryable leaf value.
+export const _optArrayLeafValue: Predicate<OptArrayDoc> = { tags: ["x"] };

packages/protocol/src/collection-api.ts

@@ -220,7 +220,12 @@ type _AllPaths<T, D extends _PathDepth[number] = 4> = [D] extends [never]
     ? keyof _StripIndex<T> & string extends never
       ? string
       : {
-          [K in keyof _StripIndex<T> & string]: _IsPathLeaf<T[K]> extends true
+          // Leaf test runs on `NonNullable<T[K]>`: for an optional field the raw
+          // `T[K]` is `V | undefined`, and the `undefined` arm defeats the
+          // array-is-a-leaf check in `_IsPathLeaf` (a union doesn't extend
+          // `ReadonlyArray`), which would otherwise make an optional `string[]`
+          // descend into `Array.prototype` and synthesize `foo.map.${string}`.
+          [K in keyof _StripIndex<T> & string]: _IsPathLeaf<NonNullable<T[K]>> extends true
             ? K
             : K | `${K}.${_AllPaths<NonNullable<T[K]>, _PathDepth[D]>}`;
         }[keyof _StripIndex<T> & string]

packages/server/API.md

@@ -34,6 +34,8 @@ import {
   MemoryStorage, // in-memory `Storage`; canonical for tests
   type Collection,
   type Query,
+  type Predicate, // equality-object `.where(...)` form
+  type PredicateArg, // `.where(...)` arg: object or builder callback
   type DocumentData,
   type RowOf,
   type CollectionNames, // row-shape inference from a bound config
@@ -59,6 +61,8 @@ import {
   type ClientQuery,
   type TerminalOptions,
   type Fetcher,
+  type Predicate,
+  type PredicateArg,
 } from "@gusto/baerly-storage/client";
 
 // Auth verifiers

packages/server/src/index.ts

@@ -52,6 +52,10 @@ export { type SchemaIssue, type SchemaValidator, validateOrThrow } from "./schem
  * - {@link Query} / {@link Collection}: the locked predicate-AST
  *   interfaces returned by `Db.collection(...)`. Consumers that
  *   destructure the chain need the named types.
+ * - {@link Predicate} / {@link PredicateArg}: the equality-object and
+ *   `.where(...)`-argument shapes. Consumers writing a helper that
+ *   forwards a predicate — or naming a collection handle in a shared
+ *   interface — need these instead of hand-rolling a structural shim.
  * - {@link Storage} + its result types
  *   ({@link StorageGetResult}, {@link StorageListEntry},
  *   {@link StoragePutResult}): the interface every storage adapter
@@ -74,6 +78,8 @@ export {
   type StorageListEntry,
   type StoragePutResult,
   type Collection,
+  type Predicate,
+  type PredicateArg,
   type Verifier,
   type VerifierResult,
 } from "@baerly/protocol";