@prisma-next/mongo-query-builder 0.0.1

package/src/field-accessor.ts

@@ -0,0 +1,280 @@
+import type {
+  MongoAggExpr,
+  MongoFilterExpr,
+  MongoUpdatePipelineStage,
+} from '@prisma-next/mongo-query-ast/execution';
+import {
+  MongoAddFieldsStage,
+  MongoAggFieldRef,
+  MongoExistsExpr,
+  MongoFieldFilter,
+  MongoProjectStage,
+  MongoReplaceRootStage,
+} from '@prisma-next/mongo-query-ast/execution';
+import type { MongoValue } from '@prisma-next/mongo-value';
+import type { NestedDocShape, ObjectField, ResolvePath, ValidPaths } from './resolve-path';
+import type { DocField, DocShape, TypedAggExpr } from './types';
+import type { TypedUpdateOp } from './update-ops';
+import {
+  addToSetOp,
+  currentDateOp,
+  incOp,
+  maxOp,
+  minOp,
+  mulOp,
+  popOp,
+  pullAllOp,
+  pullOp,
+  pushOp,
+  renameOp,
+  setOnInsertOp,
+  setOp,
+  unsetOp,
+} from './update-ops';
+
+/**
+ * Operator surface for leaf (scalar) paths — today's full set: filter,
+ * update, and aggregation operators. Returned by `Expression<F>` for any
+ * `F extends DocField` that is not an `ObjectField<…>` sub-tree.
+ *
+ * Operator surfaces are intentionally not trait-gated by codec in this
+ * revision — tracked on Linear as TML-2259 (scope extended to cover the
+ * query-builder's `Expression<F>`). Calling, e.g. `.inc(1)` on a
+ * string-typed expression compiles; the runtime relies on Mongo to
+ * surface the error. Trait-gating can be tightened in a follow-up
+ * without changing the accessor's public shape.
+ */
+export interface LeafExpression<F extends DocField> extends TypedAggExpr<F> {
+  readonly _path: string;
+
+  // Filter operators
+  eq(value: MongoValue): MongoFilterExpr;
+  ne(value: MongoValue): MongoFilterExpr;
+  gt(value: MongoValue): MongoFilterExpr;
+  gte(value: MongoValue): MongoFilterExpr;
+  lt(value: MongoValue): MongoFilterExpr;
+  lte(value: MongoValue): MongoFilterExpr;
+  in(values: ReadonlyArray<MongoValue>): MongoFilterExpr;
+  nin(values: ReadonlyArray<MongoValue>): MongoFilterExpr;
+  exists(flag?: boolean): MongoFilterExpr;
+
+  // Update operators ($set family)
+  set(value: MongoValue): TypedUpdateOp;
+  unset(): TypedUpdateOp;
+  rename(newName: string): TypedUpdateOp;
+
+  // Numeric update operators
+  inc(amount: number): TypedUpdateOp;
+  mul(factor: number): TypedUpdateOp;
+  min(value: MongoValue): TypedUpdateOp;
+  max(value: MongoValue): TypedUpdateOp;
+
+  // Array update operators
+  push(value: MongoValue): TypedUpdateOp;
+  addToSet(value: MongoValue): TypedUpdateOp;
+  pop(direction?: 1 | -1): TypedUpdateOp;
+  pull(value: MongoValue): TypedUpdateOp;
+  pullAll(values: ReadonlyArray<MongoValue>): TypedUpdateOp;
+
+  // Date / upsert helpers
+  currentDate(): TypedUpdateOp;
+  setOnInsert(value: MongoValue): TypedUpdateOp;
+}
+
+/**
+ * Operator surface for non-leaf (value-object) paths — `f('address')`
+ * when `address` is a `ContractValueObject`. Intentionally minimal: the
+ * whole-value ops that make sense on a structured sub-document
+ * (`set`/`unset`/`exists`, null presence via `eq(null)`/`ne(null)`). Field-
+ * level ops belong on the constituent leaves (`f('address.city')`).
+ *
+ * The aggregation `node` is still present (`TypedAggExpr<ObjectField<N>>`)
+ * so the value object can be piped through `$addFields` /
+ * `$replaceRoot` / etc. as-is.
+ */
+export interface ObjectExpression<N extends NestedDocShape> extends TypedAggExpr<ObjectField<N>> {
+  readonly _path: string;
+
+  exists(flag?: boolean): MongoFilterExpr;
+  eq(value: null): MongoFilterExpr;
+  ne(value: null): MongoFilterExpr;
+
+  set(value: MongoValue): TypedUpdateOp;
+  unset(): TypedUpdateOp;
+}
+
+/**
+ * The unified field accessor expression returned by `FieldAccessor` (per
+ * [ADR 180](../../../../docs/architecture%20docs/adrs/ADR%20180%20-%20Dot-path%20field%20accessor.md)).
+ *
+ * Resolves to `ObjectExpression<Sub>` when `F` is an `ObjectField<Sub>`
+ * (non-leaf path), otherwise to `LeafExpression<F>` (the full operator
+ * surface). The conditional is driven off the `fields` marker that
+ * `ObjectField` adds to `DocField`, so existing code that uses plain
+ * `DocField` shapes continues to resolve to `LeafExpression`.
+ */
+export type Expression<F extends DocField> =
+  F extends ObjectField<infer N> ? ObjectExpression<N> : LeafExpression<F>;
+
+/**
+ * Emitters for MongoDB update-pipeline stages (`$addFields`/`$set`,
+ * `$project`/`$unset`, `$replaceRoot`/`$replaceWith`). These return
+ * `MongoUpdatePipelineStage` nodes and let an updater callback express
+ * the pipeline-form update as an alternative to the typed-operator form.
+ *
+ * The two forms are mutually exclusive per updater call: `resolveUpdaterResult`
+ * rejects arrays that mix `TypedUpdateOp` and `MongoUpdatePipelineStage`
+ * entries with a clear error — an updater callback must return either all
+ * typed ops or all pipeline stages. Pick the form that matches the update
+ * you want and commit to it for that call site.
+ *
+ * Accessible via `f.stage` on the `FieldAccessor`.
+ */
+export interface StageEmitters {
+  set(fields: Record<string, MongoAggExpr>): MongoUpdatePipelineStage;
+  unset(...paths: ReadonlyArray<string>): MongoUpdatePipelineStage;
+  replaceRoot(newRoot: MongoAggExpr): MongoUpdatePipelineStage;
+  replaceWith(newRoot: MongoAggExpr): MongoUpdatePipelineStage;
+}
+
+function buildStageEmitters(): StageEmitters {
+  return {
+    set: (fields) => new MongoAddFieldsStage(fields),
+    unset: (...paths) => {
+      const spec: Record<string, 0> = {};
+      for (const p of paths) {
+        spec[p] = 0;
+      }
+      return new MongoProjectStage(spec);
+    },
+    replaceRoot: (newRoot) => new MongoReplaceRootStage(newRoot),
+    replaceWith: (newRoot) => new MongoReplaceRootStage(newRoot),
+  };
+}
+
+/**
+ * The unified `FieldAccessor` per ADR 180.
+ *
+ * - Property access (`f.status`) returns an `Expression<F>` whose codec
+ *   comes from the current pipeline shape `S`.
+ * - Callable form (`f('address.city')`) returns an `Expression<ResolvePath<N, P>>`
+ *   where `N` is the nested shape carrying value-object sub-shapes.
+ *   Paths that don't exist in `N` are rejected with a compile-time error
+ *   (via `P extends ValidPaths<N>`). Non-leaf paths like `f('address')`
+ *   resolve to an `ObjectExpression` whose reduced surface covers the
+ *   whole-value operations (`set`, `unset`, `exists`, `eq(null)`,
+ *   `ne(null)`).
+ * - `f.rawPath('path')` is a deliberate escape hatch that skips path
+ *   validation and returns a `LeafExpression<F>` for the given string.
+ *   Intended for migration authoring where the target field is not yet
+ *   part of the typed contract (e.g. a backfill writing a newly-added
+ *   column before the contract hash rolls forward). The method name is
+ *   deliberately `rawPath` rather than `raw` so it does not shadow a
+ *   legitimate top-level `raw` field on a user model.
+ * - `f.stage` exposes pipeline-style update emitters (`$set`, `$unset`,
+ *   `$replaceRoot`, `$replaceWith`).
+ *
+ * When `N` is `Record<string, never>` (the default — e.g. after a
+ * replacement stage like `$group` / `$project` / `$replaceRoot`),
+ * `ValidPaths<N>` is `never` and the callable form is effectively
+ * disabled at the type level. This keeps the builder sound downstream of
+ * stages that invalidate the original document's nested-path tree.
+ * `f.rawPath(...)` remains available in that state for callers that need
+ * an explicit unvalidated path.
+ */
+export type FieldAccessor<S extends DocShape, N extends NestedDocShape = Record<string, never>> = {
+  readonly [K in keyof S & string]: Expression<S[K]>;
+} & (<P extends ValidPaths<N>>(path: P) => Expression<ResolvePath<N, P>>) & {
+    readonly stage: StageEmitters;
+    /**
+     * Escape hatch: build a `LeafExpression<F>` for an unvalidated string
+     * path. Use only when the path is intentionally outside the typed
+     * model surface — data-migration authoring is the canonical case
+     * (e.g. backfilling a field that is not yet in the contract). Default
+     * `F` is the opaque `DocField`; callers can narrow via the explicit
+     * generic: `f.rawPath<StringField>("status").set("active")`.
+     *
+     * The method is named `rawPath` (not `raw`) so a user model with a
+     * top-level `raw` field still resolves `f.raw` to the field-expression
+     * property, not to this escape hatch. Does not participate in
+     * `ValidPaths<N>` / `ResolvePath<N, P>` — the path is passed through
+     * verbatim and no IDE autocomplete is offered.
+     */
+    rawPath<F extends DocField = DocField>(path: string): LeafExpression<F>;
+  };
+
+function buildExpression<F extends DocField>(path: string): Expression<F> {
+  // The runtime object carries the full operator surface unconditionally;
+  // `ObjectExpression` is a strict subset of `LeafExpression`, so a single
+  // implementation satisfies both type-level shapes. Compile-time gating
+  // prevents misuse of leaf-only operators on object paths.
+  return {
+    _field: undefined as never,
+    _path: path,
+    node: MongoAggFieldRef.of(path),
+
+    eq: (value: MongoValue) => MongoFieldFilter.eq(path, value),
+    ne: (value: MongoValue) => MongoFieldFilter.neq(path, value),
+    gt: (value: MongoValue) => MongoFieldFilter.gt(path, value),
+    gte: (value: MongoValue) => MongoFieldFilter.gte(path, value),
+    lt: (value: MongoValue) => MongoFieldFilter.lt(path, value),
+    lte: (value: MongoValue) => MongoFieldFilter.lte(path, value),
+    in: (values: ReadonlyArray<MongoValue>) => MongoFieldFilter.in(path, values),
+    nin: (values: ReadonlyArray<MongoValue>) => MongoFieldFilter.nin(path, values),
+    exists: (flag?: boolean) =>
+      flag === false ? MongoExistsExpr.notExists(path) : MongoExistsExpr.exists(path),
+
+    set: (value: MongoValue) => setOp(path, value),
+    unset: () => unsetOp(path),
+    rename: (newName: string) => renameOp(path, newName),
+
+    inc: (amount: number) => incOp(path, amount),
+    mul: (factor: number) => mulOp(path, factor),
+    min: (value: MongoValue) => minOp(path, value),
+    max: (value: MongoValue) => maxOp(path, value),
+
+    push: (value: MongoValue) => pushOp(path, value),
+    addToSet: (value: MongoValue) => addToSetOp(path, value),
+    pop: (direction: 1 | -1 = 1) => popOp(path, direction),
+    pull: (value: MongoValue) => pullOp(path, value),
+    pullAll: (values: ReadonlyArray<MongoValue>) => pullAllOp(path, values),
+
+    currentDate: () => currentDateOp(path),
+    setOnInsert: (value: MongoValue) => setOnInsertOp(path, value),
+  } as unknown as Expression<F>;
+}
+
+/**
+ * Construct a unified `FieldAccessor<S, N>` proxy. Property access creates
+ * an `Expression` using the property name as the field path; callable
+ * form accepts a dot-path string validated against `N` at compile time.
+ *
+ * The proxy target is a function so the resulting object is both callable
+ * and indexable. Symbol-keyed accesses (e.g. `Symbol.toPrimitive`) return
+ * `undefined` to keep accidental coercion behaviour unsurprising —
+ * matching the previous `FieldProxy` / `FilterProxy` semantics.
+ */
+export function createFieldAccessor<
+  S extends DocShape,
+  N extends NestedDocShape = Record<string, never>,
+>(): FieldAccessor<S, N> {
+  const stageInstance = buildStageEmitters();
+  const callable = ((path: string) => buildExpression<DocField>(path)) as unknown as FieldAccessor<
+    S,
+    N
+  >;
+  return new Proxy(callable, {
+    get(target, prop, receiver) {
+      if (typeof prop === 'symbol') {
+        return Reflect.get(target, prop, receiver);
+      }
+      if (prop === 'stage') {
+        return stageInstance;
+      }
+      if (prop === 'rawPath') {
+        return (path: string) => buildExpression<DocField>(path);
+      }
+      return buildExpression(prop);
+    },
+  });
+}

package/src/markers.ts

@@ -0,0 +1,25 @@
+/**
+ * Phantom capability markers for `PipelineChain`.
+ *
+ * `UpdateEnabled`          — gates `.updateMany()` / `.updateOne()` no-arg form
+ *                            (consume accumulated pipeline as an update-with-pipeline spec).
+ * `FindAndModifyEnabled`   — gates `.findOneAndUpdate(...)` / `.findOneAndDelete(...)`
+ *                            (deconstruct pipeline into the wire command's filter/sort/skip slots).
+ * `LeadingMatch`           — internal marker tracking whether the chain is still
+ *                            in its leading-`$match` prefix. Flips to `'past-leading'`
+ *                            after the first non-`$match` stage, which lets
+ *                            `match()` clear `UpdateEnabled` on second `$match`
+ *                            stages that sit past the prefix (and would otherwise
+ *                            fail at runtime inside `deconstructUpdateChain`).
+ *
+ * Each pipeline-stage method either preserves or clears these markers per
+ * the marker table (and rationale per row) in
+ * `docs/architecture docs/adrs/ADR 201 - State-machine pattern for typed DSL builders.md`.
+ *
+ * The markers exist only at the type level; nothing reads them at runtime.
+ * Value literals are self-identifying so the slots are distinguishable in
+ * hover tooltips and error messages (e.g. `'update-ok'` vs `'fam-ok'`).
+ */
+export type UpdateEnabled = 'update-ok' | 'update-cleared';
+export type FindAndModifyEnabled = 'fam-ok' | 'fam-cleared';
+export type LeadingMatch = 'leading' | 'past-leading';

package/src/query.ts

@@ -0,0 +1,55 @@
+import type { PlanMeta } from '@prisma-next/contract/types';
+import type {
+  MongoContract,
+  MongoContractWithTypeMaps,
+  MongoTypeMaps,
+} from '@prisma-next/mongo-contract';
+import type { AnyMongoCommand, MongoQueryPlan } from '@prisma-next/mongo-query-ast/execution';
+import { asMongoContract, type CollectionHandle, createCollectionHandle } from './state-classes';
+
+/**
+ * Public entry point of the query builder. `mongoQuery(...).from(rootName)`
+ * yields the root state of the three-state machine
+ * (`CollectionHandle` → `FilteredCollection` → `PipelineChain`).
+ *
+ * `rawCommand(cmd)` is the escape hatch for cases the typed surface does
+ * not cover (yet) — it accepts any `AnyMongoCommand` (typed CRUD or a
+ * `RawMongoCommand` of `Document`s) and packages it into a `MongoQueryPlan`
+ * with `lane: 'mongo-query'`. Row type is `unknown` because the runtime
+ * cannot know what the caller's command yields.
+ */
+export interface QueryRoot<
+  TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>,
+> {
+  from<K extends keyof TContract['roots'] & string>(
+    rootName: K,
+  ): CollectionHandle<TContract, TContract['roots'][K] & string & keyof TContract['models']>;
+  rawCommand<C extends AnyMongoCommand>(command: C): MongoQueryPlan<unknown, C>;
+}
+
+export function mongoQuery<
+  TContract extends MongoContractWithTypeMaps<MongoContract, MongoTypeMaps>,
+>(options: { contractJson: unknown }): QueryRoot<TContract> {
+  const contract = options.contractJson as TContract;
+  return {
+    from<K extends keyof TContract['roots'] & string>(rootName: K) {
+      return createCollectionHandle(contract, rootName);
+    },
+    rawCommand<C extends AnyMongoCommand>(command: C): MongoQueryPlan<unknown, C> {
+      const c = asMongoContract(contract);
+      const storageHash = c.storage?.storageHash;
+      if (!storageHash) {
+        throw new Error(
+          'Contract is missing storage.storageHash. Pass a validated contract to mongoQuery().',
+        );
+      }
+      const meta: PlanMeta = {
+        target: 'mongo',
+        storageHash: String(storageHash),
+        lane: 'mongo-query',
+        paramDescriptors: [],
+      };
+      return { collection: command.collection, command, meta };
+    },
+  };
+}

package/src/resolve-path.ts

@@ -0,0 +1,199 @@
+import type { MongoContract } from '@prisma-next/mongo-contract';
+import type { DocField } from './types';
+
+/**
+ * Marker `DocField` variant representing a non-leaf (value-object) path in
+ * a [NestedDocShape]. Extends `DocField` with a `fields` property carrying
+ * the sub-shape so the pipeline builder can recurse into it.
+ *
+ * `codecId` is the reserved literal `'prisma/object@1'`; the accessor's
+ * runtime implementation does not serialize it — the codec id is a purely
+ * type-level sentinel used by `Expression<F>` to select the reduced
+ * operator surface for non-leaf paths.
+ *
+ * `nullable` tracks whether the value object itself may be absent/null on
+ * the parent document. The callable form currently does not propagate the
+ * parent's `nullable` flag onto leaves beneath it (path traversal under a
+ * nullable parent resolves to the leaf's own `nullable` — matching how
+ * MongoDB treats missing intermediate documents).
+ */
+export interface ObjectField<N extends NestedDocShape> extends DocField {
+  readonly codecId: 'prisma/object@1';
+  readonly nullable: boolean;
+  readonly fields: N;
+}
+
+/**
+ * Document shape that carries nested value-object sub-shapes.
+ *
+ * Structurally identical to a flat `DocShape` (`Record<string, DocField>`),
+ * but individual values may be `ObjectField<SubShape>` carrying a nested
+ * `NestedDocShape` sub-tree. The pipeline builder threads a
+ * `NestedDocShape` alongside the flat `DocShape` so the callable
+ * `f('a.b.c')` form can validate dot-paths at the type level.
+ *
+ * When a stage transforms the root shape in a way that invalidates nested
+ * paths (e.g. `$group`, `$project`, `$replaceRoot`), the thread is reset
+ * to the empty shape `Record<string, never>` — which makes `ValidPaths`
+ * resolve to `never` and so disables the callable form downstream.
+ */
+export type NestedDocShape = Record<string, DocField>;
+
+// ── Contract → NestedDocShape translation ────────────────────────────────
+
+type ContractHasValueObjects = {
+  readonly valueObjects?: Record<string, { readonly fields: Record<string, unknown> }>;
+};
+
+type FieldToLeaf<F> = F extends {
+  readonly type: { readonly kind: 'scalar'; readonly codecId: infer C extends string };
+  readonly nullable: infer N extends boolean;
+}
+  ? { readonly codecId: C; readonly nullable: N }
+  : F extends { readonly many: true; readonly nullable: infer N extends boolean }
+    ? { readonly codecId: 'mongo/array@1'; readonly nullable: N }
+    : DocField;
+
+/**
+ * Translate a single contract field to its nested-shape form. Scalars
+ * become `DocField` leaves; value-object fields become
+ * `ObjectField<Sub>`; `many: true` stops at a leaf; anything else falls
+ * through to the opaque `DocField` base.
+ *
+ * Kept as a per-field helper (rather than a `Fields → NestedShape` helper
+ * that maps over keys internally) so the parent mapped type stays
+ * homomorphic over the model/value-object `fields` record. Homomorphic
+ * mapped types preserve the literal keys of their source object through
+ * TypeScript's intersection-collapsing machinery, which keeps
+ * `ModelNestedShape` hover output and `keyof`/indexed-access resolution
+ * concrete instead of collapsing to `{ [x: string]: … }`.
+ */
+type TranslateField<TContract extends ContractHasValueObjects, F> = F extends {
+  readonly many: true;
+}
+  ? FieldToLeaf<F>
+  : F extends {
+        readonly type: {
+          readonly kind: 'valueObject';
+          readonly name: infer VOName extends string;
+        };
+        readonly nullable: infer Null extends boolean;
+      }
+    ? ObjectField<VONestedShape<TContract, VOName>> & { readonly nullable: Null }
+    : F extends {
+          readonly type: { readonly kind: 'scalar'; readonly codecId: string };
+        }
+      ? FieldToLeaf<F>
+      : DocField;
+
+/**
+ * Resolve a named value object from the contract into its own
+ * `NestedDocShape`. The mapped iteration is inlined here (not delegated
+ * to a generic helper) so that the homomorphism over
+ * `VOs[VOName]['fields']` is preserved and the hover / indexed-access
+ * surface stays concrete at instantiation time.
+ */
+type VONestedShape<
+  TContract extends ContractHasValueObjects,
+  VOName extends string,
+> = TContract extends {
+  readonly valueObjects: infer VOs extends Record<
+    string,
+    { readonly fields: Record<string, unknown> }
+  >;
+}
+  ? VOName extends keyof VOs
+    ? {
+        readonly [K in keyof VOs[VOName]['fields'] & string]: TranslateField<
+          TContract,
+          VOs[VOName]['fields'][K]
+        >;
+      }
+    : never
+  : never;
+
+/**
+ * Build the `NestedDocShape` for a model. Scalar leaves resolve to their
+ * concrete codec id; value-object fields recurse into the referenced
+ * `valueObjects[VOName].fields` table, producing a tree that
+ * `ResolvePath` / `ValidPaths` can walk.
+ *
+ * The mapped iteration is inlined (not hidden behind a helper type that
+ * takes `Fields` as a generic) so TypeScript recognises the mapped type
+ * as homomorphic over `TContract['models'][ModelName]['fields']`. That
+ * preserves the literal field-name keys at instantiation — without this,
+ * the intersection of `Record<string, ContractField>` and the specific
+ * literal field record collapses `keyof` to `string` and the result hover
+ * degrades to `{ readonly [x: string]: any }`.
+ */
+export type ModelNestedShape<
+  TContract extends MongoContract,
+  ModelName extends string & keyof TContract['models'],
+> = {
+  readonly [K in keyof TContract['models'][ModelName]['fields'] & string]: TranslateField<
+    TContract & ContractHasValueObjects,
+    TContract['models'][ModelName]['fields'][K]
+  >;
+};
+
+// ── Path walking ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve a dot-path against a `NestedDocShape`. Returns:
+ *  - the leaf `DocField` when `Path` terminates on a scalar/array leaf,
+ *  - the `ObjectField<Sub>` when `Path` terminates on a value object (so
+ *    the caller can operate on the whole sub-document),
+ *  - `never` when the path is invalid (unknown segment, or a scalar
+ *    segment followed by further traversal).
+ *
+ * Paired with the constrained callable `<P extends ValidPaths<N>>(path: P)
+ * => Expression<ResolvePath<N, P>>` so the IDE offers completions and
+ * rejects bad paths with a clear error instead of silently resolving to
+ * `never`.
+ */
+export type ResolvePath<
+  N extends NestedDocShape,
+  Path extends string,
+> = Path extends `${infer Head}.${infer Rest}`
+  ? Head extends keyof N & string
+    ? N[Head] extends ObjectField<infer Sub>
+      ? ResolvePath<Sub, Rest>
+      : never
+    : never
+  : Path extends keyof N & string
+    ? N[Path]
+    : never;
+
+/**
+ * Union of every valid dot-path within a `NestedDocShape`. Includes
+ * top-level keys (scalar leaves *and* value-object roots) and every
+ * recursive descent through `ObjectField` sub-shapes.
+ *
+ * Non-leaf paths are intentionally included — `f('address')` yields an
+ * `Expression<ObjectField<…>>` whose reduced operator surface (`set`,
+ * `unset`, `exists`, `eq(null)`, `ne(null)`) lets callers operate on the
+ * whole value object. Leaf paths like `f('address.city')` get the full
+ * leaf operator surface.
+ *
+ * The `string extends keyof N` guard short-circuits to `never` for
+ * open-ended index-signature shapes (e.g. the default
+ * `Record<string, never>` used to represent "no nested information" —
+ * notably downstream of replacement stages in the pipeline builder). An
+ * open-ended `keyof` cannot resolve a specific literal path, so the
+ * callable form must be disabled at the type level.
+ */
+export type ValidPaths<N extends NestedDocShape> = string extends keyof N
+  ? never
+  : {
+      [K in keyof N & string]: N[K] extends ObjectField<infer Sub>
+        ? K | `${K}.${ValidPaths<Sub>}`
+        : K;
+    }[keyof N & string];
+
+/**
+ * IDE-oriented alias for `ValidPaths`. Kept as a separate export so future
+ * refinements (e.g. ArkType-style lazy expansion for very deep shapes) can
+ * diverge from the strict `ValidPaths` constraint without breaking
+ * downstream consumers. For now the two are intentionally equivalent.
+ */
+export type PathCompletions<N extends NestedDocShape> = ValidPaths<N>;