refactor(mongo-query-builder): rename f.raw -> f.rawPath to avoid shadowing real fields

The escape hatch was originally named `raw`, which silently shadowed any
legitimate top-level `raw` field on a user model: the intersection of
the mapped-type property form and the extra method both resolve at
`f.raw`, and the runtime Proxy intercepted `raw` before falling through
to `buildExpression`, so property access for a real `raw` field became
unreachable. The callable fallback `f("raw")` does not cover this case
either — the callable is disabled downstream of replacement stages, so
such a field would be permanently inaccessible once a `project` / `group`
/ `replaceRoot` was introduced.

Rename the escape hatch to `rawPath` so it lives off the property
namespace. The name also reads as exactly what it is: a raw, unvalidated
path string. All call sites in the query-builder tests, the retail-store
`backfill-product-status` migration, README, ADR 180, spec, and plan
are updated. A regression type test in field-accessor.test-d.ts pins the
non-shadowing guarantee for a model with a top-level `raw` field.

Addresses PR #361 review comment from CodeRabbit
(discussion_r3118221588, TML-2281 review round 2).

Author: wmadden

docs/architecture docs/adrs/ADR 180 - Dot-path field accessor.md

@@ -1,6 +1,6 @@
 # ADR 180 — Dot-path field accessor
 
-> **Implementation update (Mongo query builder unification).** The consolidated `FieldAccessor` shipped in `@prisma-next/mongo-query-builder` replaced the earlier `FieldProxy` and `FilterProxy` types — filter and update operators now hang off a single accessor, used by both read callbacks (`match`, `addFields`, `project`, `group`) and write callbacks (`updateMany`, `findOneAndUpdate`, etc.). Type-safe dot-path validation for the callable form `f("address.city")` was implemented in [TML-2281](https://linear.app/prisma-company/issue/TML-2281): a second generic `N extends NestedDocShape` threads the contract's model + value-object structure through the pipeline, paths are constrained by `ValidPaths<N>`, the resolved leaf's codec drives the returned `Expression`, and non-leaf paths surface a reduced `ObjectExpression` operator surface. Additive pipeline stages preserve `N`; replacement stages (`project`, `group`, `replaceRoot`, …) reset it, disabling the callable form downstream. For paths that are intentionally outside the typed model (canonically, migration authoring where a backfill writes a field that is not yet in the contract), `f.raw("path")` is the sanctioned escape hatch — it returns a `LeafExpression<DocField>` with the verbatim path and the full leaf operator surface.
+> **Implementation update (Mongo query builder unification).** The consolidated `FieldAccessor` shipped in `@prisma-next/mongo-query-builder` replaced the earlier `FieldProxy` and `FilterProxy` types — filter and update operators now hang off a single accessor, used by both read callbacks (`match`, `addFields`, `project`, `group`) and write callbacks (`updateMany`, `findOneAndUpdate`, etc.). Type-safe dot-path validation for the callable form `f("address.city")` was implemented in [TML-2281](https://linear.app/prisma-company/issue/TML-2281): a second generic `N extends NestedDocShape` threads the contract's model + value-object structure through the pipeline, paths are constrained by `ValidPaths<N>`, the resolved leaf's codec drives the returned `Expression`, and non-leaf paths surface a reduced `ObjectExpression` operator surface. Additive pipeline stages preserve `N`; replacement stages (`project`, `group`, `replaceRoot`, …) reset it, disabling the callable form downstream. For paths that are intentionally outside the typed model (canonically, migration authoring where a backfill writes a field that is not yet in the contract), `f.rawPath("path")` is the sanctioned escape hatch — it returns a `LeafExpression<DocField>` with the verbatim path and the full leaf operator surface. The method is named `rawPath` rather than `raw` so the escape hatch does not shadow a legitimate top-level `raw` field on a user model (the callable fallback `f("raw")` is disabled downstream of replacement stages, which would otherwise leave such a field inaccessible).
 
 ## At a glance
 

examples/retail-store/migrations/20260416_backfill-product-status/migration.ts

@@ -19,25 +19,26 @@ class BackfillProductStatus extends Migration {
     return [
       dataTransform('backfill-product-status', {
         check: {
-          // `status` is not part of the typed Product shape (it's the field we
-          // are backfilling), so use the `f.raw(...)` escape hatch — the
-          // strict callable `f("status")` would reject an unknown path per
-          // TML-2281. `f.raw` yields the full leaf operator surface with no
-          // contract validation; this is the sanctioned pattern for
+          // `status` is not part of the typed Product shape (it's the field
+          // we are backfilling), so use the `f.rawPath(...)` escape hatch —
+          // the strict callable `f("status")` would reject an unknown path
+          // per TML-2281. `f.rawPath` yields the full leaf operator surface
+          // with no contract validation; this is the sanctioned pattern for
           // migration authoring where the target field is not yet part of
-          // the contract. See ADR 180 and @prisma-next/mongo-query-builder's
-          // README.
+          // the contract. The method is named `rawPath` (not `raw`) so it
+          // does not shadow a legitimate top-level `raw` field on a user
+          // model. See ADR 180 and @prisma-next/mongo-query-builder's README.
           source: () =>
             query
               .from('products')
-              .match((f) => f.raw('status').exists(false))
+              .match((f) => f.rawPath('status').exists(false))
               .limit(1),
         },
         run: () =>
           query
             .from('products')
-            .match((f) => f.raw('status').exists(false))
-            .updateMany((f) => [f.raw('status').set('active')]),
+            .match((f) => f.rawPath('status').exists(false))
+            .updateMany((f) => [f.rawPath('status').set('active')]),
       }),
     ];
   }

packages/2-mongo-family/5-query-builders/query-builder/src/field-accessor.ts

@@ -164,11 +164,13 @@ function buildStageEmitters(): StageEmitters {
  *   resolve to an `ObjectExpression` whose reduced surface covers the
  *   whole-value operations (`set`, `unset`, `exists`, `eq(null)`,
  *   `ne(null)`).
- * - `f.raw('path')` is a deliberate escape hatch that skips path
+ * - `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).
+ *   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`).
  *
@@ -177,8 +179,8 @@ function buildStageEmitters(): StageEmitters {
  * `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.raw(...)` remains available in that state for callers that need an
- * explicit unvalidated path.
+ * `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]>;
@@ -190,12 +192,15 @@ export type FieldAccessor<S extends DocShape, N extends NestedDocShape = Record<
      * 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.raw<StringField>("status").set("active")`.
+     * generic: `f.rawPath<StringField>("status").set("active")`.
      *
-     * Does not participate in `ValidPaths<N>` / `ResolvePath<N, P>` — the
-     * path is passed through verbatim and no IDE autocomplete is offered.
+     * 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.
      */
-    raw<F extends DocField = DocField>(path: string): LeafExpression<F>;
+    rawPath<F extends DocField = DocField>(path: string): LeafExpression<F>;
   };
 
 function buildExpression<F extends DocField>(path: string): Expression<F> {
@@ -266,7 +271,7 @@ export function createFieldAccessor<
       if (prop === 'stage') {
         return stageInstance;
       }
-      if (prop === 'raw') {
+      if (prop === 'rawPath') {
         return (path: string) => buildExpression<DocField>(path);
       }
       return buildExpression(prop);

packages/2-mongo-family/5-query-builders/query-builder/test/builder.test.ts

@@ -83,12 +83,13 @@ describe('PipelineChain', () => {
       expect(callableStage.filter).toEqual(expectedFilter);
     });
 
-    // Runtime non-regression for the `f.raw(path)` escape hatch (TML-2281):
-    // the resulting expression must emit the same filter/update nodes as the
-    // strict callable form, just without compile-time path validation.
-    it('match via f.raw(path) emits identical nodes as the strict callable', () => {
+    // Runtime non-regression for the `f.rawPath(path)` escape hatch
+    // (TML-2281): the resulting expression must emit the same filter/update
+    // nodes as the strict callable form, just without compile-time path
+    // validation.
+    it('match via f.rawPath(path) emits identical nodes as the strict callable', () => {
       const rawPlan = createCustomersBuilder()
-        .match((f) => f.raw('status').exists(false))
+        .match((f) => f.rawPath('status').exists(false))
         .build();
       const rawStage = rawPlan.command.pipeline[0] as MongoMatchStage;
 

packages/2-mongo-family/5-query-builders/query-builder/test/field-accessor.test-d.ts

@@ -154,16 +154,16 @@ describe('ObjectExpression operator surface', () => {
   });
 });
 
-describe('FieldAccessor.raw escape hatch', () => {
+describe('FieldAccessor.rawPath escape hatch', () => {
   it('accepts an arbitrary string path without contract validation', () => {
     const f = createFieldAccessor<CustomerShape, CustomerNested>();
-    const expr = f.raw('status');
+    const expr = f.rawPath('status');
     expectTypeOf(expr).toExtend<LeafExpression<DocField>>();
   });
 
   it('returns the full leaf operator surface (set, exists, inc, …)', () => {
     const f = createFieldAccessor<CustomerShape, CustomerNested>();
-    const expr = f.raw('status');
+    const expr = f.rawPath('status');
     expectTypeOf(expr.set).toBeFunction();
     expectTypeOf(expr.unset).toBeFunction();
     expectTypeOf(expr.exists).toBeFunction();
@@ -173,27 +173,41 @@ describe('FieldAccessor.raw escape hatch', () => {
 
   it('accepts paths that are not in ValidPaths<N>', () => {
     const f = createFieldAccessor<CustomerShape, CustomerNested>();
-    // 'status' is not a valid path on Customer; `f.raw` must still accept
-    // it — that is the whole point of the escape hatch (migration authoring
-    // where the target field is not yet in the contract).
-    f.raw('status');
-    f.raw('deeply.nested.not.in.contract');
+    // 'status' is not a valid path on Customer; `f.rawPath` must still
+    // accept it — that is the whole point of the escape hatch (migration
+    // authoring where the target field is not yet in the contract).
+    f.rawPath('status');
+    f.rawPath('deeply.nested.not.in.contract');
   });
 
   it('remains available when N is empty (callable disabled)', () => {
     const f = createFieldAccessor<CustomerShape>();
     // Callable (strict) is disabled because ValidPaths<{}> = never.
-    // `f.raw` has no such dependency on N and remains usable.
-    const expr = f.raw('status');
+    // `f.rawPath` has no such dependency on N and remains usable.
+    const expr = f.rawPath('status');
     expectTypeOf(expr).toExtend<LeafExpression<DocField>>();
   });
 
   it('narrows the return via the explicit generic', () => {
     const f = createFieldAccessor<CustomerShape, CustomerNested>();
     type StringField = { readonly codecId: 'mongo/string@1'; readonly nullable: false };
-    const expr = f.raw<StringField>('status');
+    const expr = f.rawPath<StringField>('status');
     expectTypeOf(expr).toEqualTypeOf<LeafExpression<StringField>>();
   });
+
+  it('does not shadow a legitimate top-level `raw` field', () => {
+    // Regression test: the escape hatch is named `rawPath`, not `raw`, so a
+    // user model with a `raw` field still resolves `f.raw` to the field
+    // expression (via the mapped-type property form) rather than to the
+    // escape-hatch function.
+    type ModelWithRawField = {
+      readonly id: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+      readonly raw: { readonly codecId: 'mongo/string@1'; readonly nullable: false };
+    };
+    const f = createFieldAccessor<ModelWithRawField>();
+    expectTypeOf(f.raw).toExtend<LeafExpression<DocField>>();
+    expectTypeOf(f.raw).not.toBeFunction();
+  });
 });
 
 describe('Pipeline integration — N threading', () => {

projects/mongo-pipeline-builder/plans/callable-field-accessor-path-validation-plan.md

@@ -119,4 +119,4 @@ Carried forward from the spec's Open Questions. These are execution-time decisio
 3. **Nullable intermediate behaviour.** Default: fold nullability downward (nullable intermediate → leaf's `nullable = true`). Implementation note for task 1.4.
 4. **Compile-time performance.** No depth cap on `PathCompletions` for v1. Monitor CI time during PR; if the query-builder package's typecheck time regresses meaningfully, add a cap and file a follow-up.
 5. **ORM callable form.** In scope only to the extent of keeping the ORM compiling. If the ORM already derives a nested shape equivalent to `N`, wire it through; otherwise leave its callable form defaulted (unusable) and file a follow-up.
-6. **Unvalidated string paths for migration authoring.** **Resolved in review round 1 (F12/F13).** Strict validation breaks backfill migrations that write to fields not yet present in the pre-migration contract (the canonical case: the `retail-store` `backfill-product-status` migration writes to `status` before the post-migration contract hash rolls forward). Resolution: add an explicit `f.raw("path")` escape hatch on `FieldAccessor` that returns `LeafExpression<DocField>` with the verbatim path, callable-form validation bypassed. Migration authoring uses `f.raw("status")` in place of `f("status")`. Additionally, example consumer tsconfigs must include `migrations/**/*.ts` so the typecheck exercises migration code (the `retail-store` tsconfig was updated accordingly). Follow-up: audit other example/package tsconfigs for the same exclusion pattern and file a separate ticket if others are found.
+6. **Unvalidated string paths for migration authoring.** **Resolved in review round 1 (F12/F13), refined in round 2 (CodeRabbit `f.raw` shadow finding).** Strict validation breaks backfill migrations that write to fields not yet present in the pre-migration contract (the canonical case: the `retail-store` `backfill-product-status` migration writes to `status` before the post-migration contract hash rolls forward). Resolution: add an explicit `f.rawPath("path")` escape hatch on `FieldAccessor` that returns `LeafExpression<DocField>` with the verbatim path, callable-form validation bypassed. Migration authoring uses `f.rawPath("status")` in place of `f("status")`. The method is named `rawPath` (not `raw`) so a user model with a legitimate top-level `raw` field still resolves `f.raw` to its field expression — `raw` on the property namespace would have silently shadowed the field, and the callable fallback `f("raw")` is disabled downstream of replacement stages. Additionally, example consumer tsconfigs must include `migrations/**/*.ts` so the typecheck exercises migration code (the `retail-store` tsconfig was updated accordingly). Follow-up: audit other example/package tsconfigs for the same exclusion pattern and file a separate ticket if others are found.