Update typed FieldMask in sdk-core (#101)

## 🥞 Stacked PR
Use this [link](https://github.com/databricks/sdk-js/pull/101/files) to
review incremental changes.
-
[**stack/field-mask-sdk-core**](#101)
[[Files changed](https://github.com/databricks/sdk-js/pull/101/files)]
-
[stack/generator-field-mask](#102)
[[Files
changed](https://github.com/databricks/sdk-js/pull/102/files/9662ed8687549fc04fb0dd2588bb8d3c5e59853b..b49f0f673265f605667d95501e6beaea9630647d)]
-
[stack/field-mask-convertors](#100)
[[Files
changed](https://github.com/databricks/sdk-js/pull/100/files/b49f0f673265f605667d95501e6beaea9630647d..7b206bc649bc57d0915f922997954ce0323ff8ef)]

---------
## Summary

Update the `FieldMask<T>` in `@databricks/sdk-core/wkt`.
`FieldMask.build` validates paths against a per-message schema,
translates them to wire format, and stores the result privately.
`toString()` serializes to the comma-separated wire string the server
expects.

## Why

Databricks accepts field-mask paths in proto snake_case, but generated
TS interfaces use camelCase. The existing `FieldMask` didn't translate
or validate — typos went silently to the server. This is the runtime
foundation the generator needs; the follow-up PR emits the per-message
schemas and factories that call `FieldMask.build`.

### Why validation is at runtime, not compile time

A compile-time `FieldPaths<T>` conditional type (computing the
string-literal union of valid paths for each generated interface) was
explored and rejected. TypeScript's conditional-type evaluation has a
hard recursion depth limit — any proto message that references itself or
forms a cycle through another message (common in Databricks' schemas:
`Node { child: Node }`, `A → B → A`) triggers `TS2589: Type
instantiation is excessively deep and possibly infinite`. Verified by
probing against the real sdk-js `tsconfig`. Because we can't express a
complete set of valid paths at the type level for the schemas we
actually ship, `FieldMask.build` walks the schema at runtime and throws
on a mismatch instead. The schema itself is a plain runtime object with
lazy `() => FieldMaskSchema` child references, which keeps recursive and
mutually-recursive protos describable as finite graphs.

## What changed

### Interface changes

- **`FieldMask<T = unknown>`** — private constructor, `@internal static
build<T>(paths, schema)` as the sole entry point, `toString(): string`
returning the joined wire paths. Phantom `T` distinguishes masks across
messages at compile time.
- **`FieldMaskSchema`, `FieldMaskSchemaField`** — new exports. The shape
the generator emits per message; `children?: () => FieldMaskSchema`
keeps recursive/mutual-recursive protos cycle-safe.
- **Removed**: `FieldPaths<T>`, `FieldMask.of(...)`,
`FieldMask.append(...)`. See the "Why validation is at runtime" note
above for the rationale.

### Behavioral changes

`FieldMask.build` throws on an unknown path segment or descent past a
scalar leaf. Before, any string was accepted.

### Internal changes

`walkFieldMaskPath` and `normalize` are module-private in
`packages/core/src/wkt/fieldmask.ts`.

## How is this tested?

Table-driven tests (`it.each`) in
`packages/core/tests/wkt/fieldmask.test.ts`:

- **Valid paths translate and serialize** (8 cases): flat, nested, deep,
multi-path sort, dedup, parent subsumption, empty input, self-cycle at
arbitrary depth.
- **Invalid paths throw** (3 cases): unknown top-level, unknown nested,
descent past scalar.

Author: parthban-db

packages/core/src/wkt/fieldmask.ts

@@ -1,49 +1,7 @@
-// True if any property of T is callable, indicating a class instance (e.g.
-// Temporal.Instant, Date) rather than a plain data interface.
-type HasMethods<T> = true extends {
-  [K in keyof T]-?: NonNullable<T[K]> extends (...args: never[]) => unknown
-    ? true
-    : never;
-}[keyof T]
-  ? true
-  : false;
-
-/**
- * Utility type that derives all valid dot-separated field paths from a
- * TypeScript interface. Provides compile-time path validation for
- * {@link FieldMask}.
- *
- * Recursion stops at arrays, index signatures (Record/Map), and class
- * instances with methods (e.g. Temporal.Instant, Date). These are treated
- * as leaf nodes.
- *
- * @example
- * ```ts
- * interface Cluster {
- *   name: string;
- *   config: {numWorkers: number; scaling: {min: number}};
- * }
- * // "name" | "config" | "config.numWorkers" | "config.scaling" | "config.scaling.min"
- * type ClusterPaths = FieldPaths<Cluster>;
- * ```
- */
-export type FieldPaths<T, Prefix extends string = ''> = {
-  [K in keyof T & string]: NonNullable<T[K]> extends unknown[]
-    ? `${Prefix}${K}` // Array field — leaf, do not recurse.
-    : NonNullable<T[K]> extends Record<string, unknown>
-      ? string extends keyof NonNullable<T[K]>
-        ? `${Prefix}${K}` // Index signature (Record/Map) — leaf, do not recurse.
-        : HasMethods<NonNullable<T[K]>> extends true
-          ? `${Prefix}${K}` // Class instance with methods — leaf, do not recurse.
-          : `${Prefix}${K}` | FieldPaths<NonNullable<T[K]>, `${Prefix}${K}.`>
-      : `${Prefix}${K}`;
-}[keyof T & string];
-
-// Remove duplicates and paths subsumed by a parent (e.g. "config" subsumes
-// "config.numWorkers").
-function normalize<P extends string>(paths: P[]): P[] {
+// Remove duplicates and paths subsumed by a parent (e.g. "config" subsumes "config.numWorkers").
+function normalize(paths: string[]): string[] {
   const unique = [...new Set(paths)].sort();
-  const result: P[] = [];
+  const result: string[] = [];
   for (const path of unique) {
     const isSubsumed = result.some(existing => path.startsWith(existing + '.'));
     if (!isSubsumed) {
@@ -54,33 +12,78 @@ function normalize<P extends string>(paths: P[]): P[] {
 }
 
 /**
- * A type-safe field mask implementing google.protobuf.FieldMask semantics.
- * Provides compile-time path validation via {@link FieldPaths}. Paths are
- * always normalized: duplicates and paths subsumed by a parent are removed.
- *
- * @example
- * ```ts
- * const mask = FieldMask.of<FieldPaths<Cluster>>(
- *   'displayName',
- *   'config.numWorkers'
- * );
- * ```
+ * One field entry in a {@link FieldMaskSchema}: its wire-format name and, for message-typed fields, a lazy reference to the nested message's schema. Array, map, enum, and scalar fields omit `children`.
  */
-export class FieldMask<TPath extends string = string> {
-  /** The list of field paths in this mask. */
-  readonly paths: TPath[];
+export interface FieldMaskSchemaField {
+  readonly wire: string;
+  readonly children?: () => FieldMaskSchema;
+}
 
-  private constructor(paths: TPath[]) {
-    this.paths = normalize(paths);
+/**
+ * Structural description of one message's FieldMask-reachable fields. Maps each typescript field name to its wire-format name and, for message-typed fields, a lazy `() => FieldMaskSchema` reference that lets recursive and mutually-recursive messages describe themselves.
+ */
+export type FieldMaskSchema = Readonly<Record<string, FieldMaskSchemaField>>;
+
+// Walk a dot-separated typescript field name path against a schema, returning the equivalent wire-format path. Returns `undefined` when any segment fails: a name that isn't a field of the current message, or a non-terminal segment that doesn't reference another message.
+function walkFieldMaskPath(
+  schema: FieldMaskSchema,
+  path: string
+): string | undefined {
+  const segments = path.split('.');
+  const wireSegments: string[] = [];
+  let current: FieldMaskSchema = schema;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    // Existence check before lookup: `current[seg]` is typed as FieldMaskSchemaField without noUncheckedIndexedAccess, so an undefined check downstream would be flagged "unnecessary".
+    if (!(seg in current)) return undefined;
+    const field = current[seg];
+    wireSegments.push(field.wire);
+    if (i < segments.length - 1) {
+      if (field.children === undefined) return undefined;
+      current = field.children();
+    }
   }
+  return wireSegments.join('.');
+}
+
+/**
+ * A field mask implementing google.protobuf.FieldMask semantics.
+ */
+export class FieldMask<T = unknown> {
+  // Phantom marker: keeps `FieldMask<Alert>` and `FieldMask<Query>` compile-time distinct under TypeScript's otherwise-structural typing. Never set at runtime.
+  declare private readonly _tag: T;
 
-  /** Create a field mask from one or more paths. */
-  static of<P extends string>(...paths: P[]): FieldMask<P> {
-    return new FieldMask(paths);
+  // Stored post-translation, normalized wire-format paths.
+  private readonly paths: string[];
+
+  private constructor(paths: string[]) {
+    this.paths = paths;
+  }
+
+  /**
+   * Build a FieldMask from typescript field name paths against the target message's schema. Validates every path by walking each segment through the schema and throws Error when any segment fails.
+   *
+   * Reserved for generated per-message factories; user code should call the factory (e.g. `alertFieldMask(...)`), which supplies the schema before delegating here.
+   *
+   * @internal
+   */
+  static build<T>(paths: string[], schema: FieldMaskSchema): FieldMask<T> {
+    const normalized = normalize(paths);
+    const wire: string[] = [];
+    for (const p of normalized) {
+      const w = walkFieldMaskPath(schema, p);
+      if (w === undefined) {
+        throw new Error(`Unknown field path "${p}"`);
+      }
+      wire.push(w);
+    }
+    return new FieldMask<T>(wire);
   }
 
-  /** Return a new mask with additional paths appended. */
-  append(...paths: TPath[]): FieldMask<TPath> {
-    return new FieldMask([...this.paths, ...paths]);
+  /**
+   * Serialize the mask to the wire-format string.
+   */
+  toString(): string {
+    return this.paths.join(',');
   }
 }

packages/core/src/wkt/index.ts

@@ -1,3 +1,3 @@
 export {FieldMask} from './fieldmask';
-export type {FieldPaths} from './fieldmask';
+export type {FieldMaskSchema, FieldMaskSchemaField} from './fieldmask';
 export type {JsonValue, JsonObject} from './value';

packages/core/tests/wkt/fieldmask.test.ts

@@ -1,133 +1,120 @@
 import {describe, it, expect} from 'vitest';
 import {FieldMask} from '../../src/wkt';
-import type {FieldPaths} from '../../src/wkt';
+import type {FieldMaskSchema} from '../../src/wkt';
 
-// Simulates a class instance with methods (e.g. Temporal.Instant).
-interface ClassLike {
-  epochMilliseconds: number;
-  toString(): string;
-}
+// Alert-like non-cyclic schema with nested Condition + Operand, used to drive FieldMask through its `@internal` build entry point.
+const operandSchema: FieldMaskSchema = {
+  column: {wire: 'column'},
+  value: {wire: 'value'},
+};
+const conditionSchema: FieldMaskSchema = {
+  op: {wire: 'op'},
+  operand: {wire: 'operand', children: () => operandSchema},
+};
+const alertSchema: FieldMaskSchema = {
+  displayName: {wire: 'display_name'},
+  condition: {wire: 'condition', children: () => conditionSchema},
+};
 
-// Test interface for FieldPaths derivation.
-interface Cluster {
-  name: string;
-  displayName: string;
-  state: string;
-  config: {
-    numWorkers: number;
-    scaling: {
-      minReplicas: number;
-      maxReplicas: number;
-    };
-  };
-  tags: string[];
-  labels: Record<string, string>;
-  createTime?: ClassLike;
-}
+// Self-referential schema used to verify cycle-safe construction.
+const nodeSchema: FieldMaskSchema = {
+  label: {wire: 'label'},
+  child: {wire: 'child', children: () => nodeSchema},
+};
 
-// Verify FieldPaths derives correct paths at compile time.
-type ClusterPaths = FieldPaths<Cluster>;
-const _checkPaths: ClusterPaths[] = [
-  'name',
-  'displayName',
-  'state',
-  'config',
-  'config.numWorkers',
-  'config.scaling',
-  'config.scaling.minReplicas',
-  'config.scaling.maxReplicas',
-  'tags',
-  'labels',
-  'createTime', // Leaf — ClassLike has methods, so no recursion.
-];
-// Suppress unused variable warning.
-void _checkPaths;
-
-// Verify that ClassLike properties are NOT included as paths.
-// If FieldPaths recursed into ClassLike, "createTime.epochMilliseconds" would
-// be a valid path. This assignment must fail at compile time.
-// @ts-expect-error - ClassLike is a leaf; its properties are not valid paths.
-const _badPath: ClusterPaths = 'createTime.epochMilliseconds';
-void _badPath;
-
-describe('FieldMask', () => {
-  describe('of', () => {
-    const testCases: {name: string; input: string[]; want: string[]}[] = [
-      {name: 'single path', input: ['name'], want: ['name']},
+describe('FieldMask.build', () => {
+  describe('valid paths translate and serialize', () => {
+    const cases: {
+      name: string;
+      schema: FieldMaskSchema;
+      input: string[];
+      want: string;
+    }[] = [
       {
-        name: 'multiple paths',
-        input: ['displayName', 'name'],
-        want: ['displayName', 'name'],
+        name: 'flat path',
+        schema: alertSchema,
+        input: ['displayName'],
+        want: 'display_name',
       },
       {
-        name: 'deduplicates paths',
-        input: ['name', 'name', 'state'],
-        want: ['name', 'state'],
+        name: 'nested path',
+        schema: alertSchema,
+        input: ['condition.op'],
+        want: 'condition.op',
       },
       {
-        name: 'removes paths subsumed by a parent',
-        input: ['config.numWorkers', 'config', 'name'],
-        want: ['config', 'name'],
+        name: 'deeply nested path',
+        schema: alertSchema,
+        input: ['condition.operand.column'],
+        want: 'condition.operand.column',
       },
       {
-        name: 'removes deeply subsumed paths',
-        input: ['config.scaling.minReplicas', 'config.scaling', 'config'],
-        want: ['config'],
+        name: 'multiple paths joined in sorted order',
+        schema: alertSchema,
+        input: ['displayName', 'condition.op'],
+        want: 'condition.op,display_name',
       },
       {
-        name: 'does not subsume paths sharing a prefix without a dot boundary',
-        input: ['foo', 'foobar'],
-        want: ['foo', 'foobar'],
+        name: 'duplicates collapse before translation',
+        schema: alertSchema,
+        input: ['displayName', 'displayName'],
+        want: 'display_name',
+      },
+      {
+        name: 'children subsumed by a parent are dropped',
+        schema: alertSchema,
+        input: ['condition.op', 'condition'],
+        want: 'condition',
+      },
+      {
+        name: 'empty input serializes to empty string',
+        schema: alertSchema,
+        input: [],
+        want: '',
+      },
+      {
+        name: 'arbitrary depth through a self-cycle',
+        schema: nodeSchema,
+        input: ['child.child.child.label'],
+        want: 'child.child.child.label',
       },
-      {name: 'empty mask', input: [], want: []},
     ];
 
-    it.each(testCases)('$name', ({input, want}) => {
-      const mask = FieldMask.of(...input);
-      expect(mask.paths).toStrictEqual(want);
+    it.each(cases)('$name', ({schema, input, want}) => {
+      const mask = FieldMask.build<unknown>(input, schema);
+      expect(mask.toString()).toBe(want);
     });
   });
 
-  describe('append', () => {
-    const testCases: {
+  describe('invalid paths throw', () => {
+    const cases: {
       name: string;
-      initial: string[];
-      append: string[];
-      want: string[];
+      schema: FieldMaskSchema;
+      input: string[];
+      msg: string;
     }[] = [
       {
-        name: 'adds new paths',
-        initial: ['name'],
-        append: ['state'],
-        want: ['name', 'state'],
+        name: 'unknown top-level field',
+        schema: alertSchema,
+        input: ['bogus'],
+        msg: 'Unknown field path "bogus"',
       },
       {
-        name: 'deduplicates when appending existing paths',
-        initial: ['name', 'state'],
-        append: ['name'],
-        want: ['name', 'state'],
+        name: 'unknown nested field',
+        schema: alertSchema,
+        input: ['condition.bogus'],
+        msg: 'Unknown field path "condition.bogus"',
       },
       {
-        name: 'subsumes child when parent is appended',
-        initial: ['config.numWorkers'],
-        append: ['config'],
-        want: ['config'],
+        name: 'descent past a scalar leaf',
+        schema: alertSchema,
+        input: ['displayName.nope'],
+        msg: 'Unknown field path "displayName.nope"',
       },
     ];
 
-    it.each(testCases)('$name', ({initial, append, want}) => {
-      const mask = FieldMask.of(...initial).append(...append);
-      expect(mask.paths).toStrictEqual(want);
-    });
-  });
-
-  describe('type safety with FieldPaths', () => {
-    it('works with derived FieldPaths type', () => {
-      const mask = FieldMask.of<FieldPaths<Cluster>>(
-        'displayName',
-        'config.numWorkers'
-      );
-      expect(mask.paths).toStrictEqual(['config.numWorkers', 'displayName']);
+    it.each(cases)('$name', ({schema, input, msg}) => {
+      expect(() => FieldMask.build<unknown>(input, schema)).toThrowError(msg);
     });
   });
 });