@pyric/cli 0.1.0-alpha.30.1 → 0.1.0-alpha.31

package/src/serve/worker/client/auth.ts

@@ -14,6 +14,7 @@ import type {
   ResolvedIdentity,
   OpMessage,
 } from '../protocol.js';
+import { FirebaseError } from 'pyric/app';
 import { absolutePhotoUrl, realmOrigin } from 'pyric/sandbox/internal';
 import { closeSubscription, isDisconnectedPort, nextId, nextSubId, openSnapshotSubscription, rpc, wirePort } from './core.js';
 import type { ClientDb, ClientPort, Unsubscribe } from './handles.js';
@@ -253,6 +254,62 @@ export async function acceptProviderCredential(
   return hydrateCred(auth, raw);
 }
 
+/** The parts of a staged `UserCredential` the host needs: who signs in, and through which provider. */
+export interface StagedSignInResult {
+  readonly user: {
+    readonly uid: string;
+    readonly email?: string | null;
+    readonly displayName?: string | null;
+    readonly photoURL?: string | null;
+  };
+  readonly providerId: string | null;
+}
+
+/**
+ * Stage the user this port's next `signInWithCredential` for
+ * `result.providerId` signs in as (served `sandbox.mockSignInResult`, #1466).
+ * Sent without waiting, as the `tenantId` setter is: the port delivers in
+ * order, so the host has it before the next sign-in. The checks the host would
+ * make run here first, so a malformed result throws at the call.
+ */
+export function stageSignInResult(auth: ClientAuth, result: StagedSignInResult): void {
+  const providerId = result.providerId;
+  const uid = result.user?.uid;
+  const hasProvider = typeof providerId === 'string' && providerId !== '';
+  const hasUid = typeof uid === 'string' && uid !== '';
+  if (!hasProvider || !hasUid) {
+    throw new FirebaseError(
+      'invalid-argument',
+      'sandbox.mockSignInResult: result.providerId and result.user.uid must be non-empty strings.',
+    );
+  }
+  const identity: ResolvedIdentity = {
+    uid,
+    providerId,
+    email: profileField(result.user.email),
+    displayName: profileField(result.user.displayName),
+    photoURL: profileField(result.user.photoURL),
+    customClaims: {},
+  };
+  // The signature is void, so an error reply (a deleted app, a refused send)
+  // has nowhere to go; the next sign-in reports auth/no-mock-configured.
+  rpc(auth.port, { t: 'op', id: nextId(), method: 'auth.mockSignInResult', identity }).catch(() => {});
+}
+
+/** A staged profile field the host accepts: a string, or null when absent. Anything else throws at the call. */
+function profileField(value: unknown): string | null {
+  const isAbsent = value === undefined || value === null;
+  if (isAbsent) return null;
+  const isString = typeof value === 'string';
+  if (!isString) {
+    throw new FirebaseError(
+      'invalid-argument',
+      'sandbox.mockSignInResult: result.user.email, displayName and photoURL must be strings or null.',
+    );
+  }
+  return value;
+}
+
 /**
  * Re-establish THIS PORT's session for an existing identity (#754).
  */
@@ -424,40 +481,59 @@ export async function updateCurrentUser(
   auth.currentUser = toClientUser(auth.port, raw);
 }
 
+/** The fields of an `AuthCredential` the served client reads. */
+type SignInCredential = {
+  providerId: string;
+  signInMethod?: string;
+  idToken?: string | null;
+  accessToken?: string | null;
+  rawNonce?: string | null;
+  email?: string | null;
+  displayName?: string | null;
+  photoURL?: string | null;
+  uid?: string | null;
+  toJSON?: () => Record<string, unknown>;
+};
+
 /**
- * OAuth Credential Sign-In (`auth.signInWithCredential`) over the SharedWorker.
+ * Credential sign-in (`auth.signInWithCredential`) over the SharedWorker.
+ * An email credential crosses as `toJSON()`, which carries its password or
+ * link, so the host can check it; an OAuth credential sends its identity fields.
  */
 export async function signInWithCredential(
   auth: ClientAuth,
-  credential: {
-    providerId: string;
-    idToken?: string | null;
-    accessToken?: string | null;
-    rawNonce?: string | null;
-    email?: string | null;
-    displayName?: string | null;
-    photoURL?: string | null;
-    uid?: string | null;
-  },
+  credential: SignInCredential,
 ): Promise<ClientUserCredential> {
   const raw = (await rpc(auth.port, {
     t: 'op',
     id: nextId(),
     method: 'auth.signInWithCredential',
-    credential: {
-      providerId: credential.providerId,
-      idToken: credential.idToken ?? null,
-      accessToken: credential.accessToken ?? null,
-      rawNonce: credential.rawNonce ?? null,
-      email: credential.email ?? null,
-      displayName: credential.displayName ?? null,
-      photoURL: credential.photoURL ?? null,
-      uid: credential.uid ?? null,
-    },
+    credential: credentialWire(credential),
   })) as SerializedUserCredential;
   return hydrateCred(auth, raw);
 }
 
+type CredentialWire = NonNullable<Extract<OpMessage, { method: 'auth.signInWithCredential' }>['credential']>;
+
+/** A credential with no sign-in method sends an empty one, which the host refuses. */
+function credentialWire(credential: SignInCredential): CredentialWire {
+  const isEmailCredential = credential.providerId === 'password';
+  if (isEmailCredential) {
+    const serialized = credential.toJSON?.() ?? {};
+    return { ...serialized, providerId: credential.providerId, signInMethod: credential.signInMethod ?? '' };
+  }
+  return {
+    providerId: credential.providerId,
+    idToken: credential.idToken ?? null,
+    accessToken: credential.accessToken ?? null,
+    rawNonce: credential.rawNonce ?? null,
+    email: credential.email ?? null,
+    displayName: credential.displayName ?? null,
+    photoURL: credential.photoURL ?? null,
+    uid: credential.uid ?? null,
+  };
+}
+
 export function beforeAuthStateChanged(): never {
   const err = new Error(
     'beforeAuthStateChanged is not supported over the SharedWorker yet.',

package/src/serve/worker/client/clock.ts

@@ -10,30 +10,28 @@
  *
  * So the state is mirrored rather than fetched. `wirePort` asks the host to
  * stream it; the host answers immediately and again on every move, and
- * {@link sandboxNow} derives the instant from the mirror using the same three
- * modes the clock itself does. A port that has not been answered yet mirrors
- * the wall clock, which is what an unmoved clock reports anyway.
+ * {@link sandboxNow} derives the instant from the mirror through the same
+ * `ClockReading` the clock itself uses, so the page applies the same modes and
+ * the same rule for a host clock that steps back. A port that has not been
+ * answered yet mirrors the wall clock, which is what an unmoved clock reports
+ * anyway.
  */
+import { ClockReading } from 'pyric/sandbox/internal';
 import type { SandboxClockState } from 'pyric/sandbox';
 
-/** The state a clock that has never been moved reports. */
-const WALL: SandboxClockState = { mode: 'wall', fixedAt: 0, offsetMs: 0 };
-
-let mirrored: SandboxClockState = WALL;
+const mirror = new ClockReading();
 
 /** Adopt the state the host just sent. */
 export function receiveClockState(state: SandboxClockState): void {
-  mirrored = state;
+  mirror.follow(state);
 }
 
 /** The state the page currently believes the sandbox clock holds. */
 export function mirroredClockState(): SandboxClockState {
-  return mirrored;
+  return mirror.state;
 }
 
 /** The sandbox's current time, in epoch milliseconds, from the mirror. */
 export function sandboxNow(): number {
-  if (mirrored.mode === 'fixed') return mirrored.fixedAt;
-  if (mirrored.mode === 'offset') return Date.now() + mirrored.offsetMs;
-  return Date.now();
+  return mirror.now();
 }

package/src/serve/worker/client/firestore-reads.ts

@@ -148,10 +148,65 @@ export async function getAggregateFromServer<S extends AggregateSpecDescriptor>(
 type SnapshotCallback = (snap: ClientDocSnapshot | ClientQuerySnapshot) => void;
 type SnapshotErrorCallback = (err: unknown) => void;
 
+/** Production's `PartialObserver`: any of `next`, `error` and `complete`. */
+export interface SnapshotObserver {
+  next?: SnapshotCallback;
+  error?: SnapshotErrorCallback;
+  complete?: () => void;
+}
+
+type ObserverOrNext = SnapshotObserver | SnapshotCallback;
+
+interface ListenerArguments {
+  readonly options: object | undefined;
+  readonly next: SnapshotCallback | undefined;
+  readonly error: SnapshotErrorCallback | undefined;
+}
+
+/**
+ * An observer is an object with at least one of `next`, `error` or
+ * `complete` as a function, as the SDK's `isPartialObserver` decides; any
+ * other object in the second slot is listen options.
+ */
+function isPartialObserver(value: unknown): value is SnapshotObserver {
+  const isObject = typeof value === 'object' && value !== null;
+  if (!isObject) return false;
+  const candidate = value as Record<string, unknown>;
+  return typeof candidate.next === 'function'
+    || typeof candidate.error === 'function'
+    || typeof candidate.complete === 'function';
+}
+
+/**
+ * Read the four call forms: `(next, error?)`, `(observer)`, `(options, next,
+ * error?)` and `(options, observer)`. `complete` is never called: production
+ * does not end an `onSnapshot` stream, and `unsubscribe` is not an end
+ * (observation `firestore-row-84-observer-object-form`).
+ */
+function listenerArguments(second: unknown, third: unknown, fourth: unknown): ListenerArguments {
+  const isOptions = typeof second === 'object' && second !== null && !isPartialObserver(second);
+  const options = isOptions ? second : undefined;
+  const handler = isOptions ? third : second;
+  const trailingError = isOptions ? fourth : third;
+  if (isPartialObserver(handler)) {
+    return { options, next: handler.next?.bind(handler), error: handler.error?.bind(handler) };
+  }
+  return {
+    options,
+    next: handler as SnapshotCallback | undefined,
+    error: trailingError as SnapshotErrorCallback | undefined,
+  };
+}
+
+/** The SDK logs a listen error nobody observes instead of throwing it. */
+function reportUncaughtListenError(error: unknown): void {
+  console.error('pyric/firestore: Uncaught Error in snapshot listener:', error);
+}
+
 /**
- * Subscribe to a document or query. Mirrors `pyric/firestore`'s `onSnapshot`,
- * including its options-second form `onSnapshot(target, options, next,
- * error)`: `@pyric/ui`'s hooks pass `{ owner }` there for listener
+ * Subscribe to a document or query. Mirrors `pyric/firestore`'s `onSnapshot`
+ * in all four call forms, with a callback or an observer, with or without
+ * options first: `@pyric/ui`'s hooks pass `{ owner }` there for listener
  * attribution, and a caller injecting this client as the hooks' backend must
  * not lose its callback to that slot. The owners are derived here, on the page
  * whose stack and DOM they describe, and travel with the subscribe message.
@@ -161,23 +216,23 @@ type SnapshotErrorCallback = (err: unknown) => void;
  */
 export function onSnapshot(
   target: DocRefHandle | CollRefHandle | QueryHandle,
-  callback: SnapshotCallback,
+  observerOrNext: ObserverOrNext,
   errorCallback?: SnapshotErrorCallback,
 ): Unsubscribe;
 export function onSnapshot(
   target: DocRefHandle | CollRefHandle | QueryHandle,
   options: object,
-  callback: SnapshotCallback,
+  observerOrNext: ObserverOrNext,
   errorCallback?: SnapshotErrorCallback,
 ): Unsubscribe;
 export function onSnapshot(
   target: DocRefHandle | CollRefHandle | QueryHandle,
-  optionsOrCallback: object | SnapshotCallback,
-  callbackOrError?: SnapshotCallback | SnapshotErrorCallback,
-  maybeError?: SnapshotErrorCallback,
+  second: object | ObserverOrNext,
+  third?: ObserverOrNext | SnapshotErrorCallback,
+  fourth?: SnapshotErrorCallback,
 ): Unsubscribe {
-  const hasDirectCallback = typeof optionsOrCallback === 'function';
-  const listenOptions = hasDirectCallback ? undefined : optionsOrCallback;
+  const { options: listenOptions, next: callback, error: errorCallback } = listenerArguments(second, third, fourth);
+  const reportError = errorCallback ?? reportUncaughtListenError;
   // Derived before the message is built: `captureCreationFrame` reads the
   // stack this call is still on.
   const owners = pageListenerOwners(listenOptions);
@@ -186,12 +241,6 @@ export function onSnapshot(
   // Kept across lens resubscriptions: the host's fresh snapshot after a
   // resubscribe is diffed against what this listener last delivered.
   const baseline: QueryChangeBaseline = { excludesMetadataChanges: !includeMetadataChanges };
-  const callback = (hasDirectCallback
-    ? optionsOrCallback
-    : callbackOrError) as SnapshotCallback;
-  const errorCallback = (hasDirectCallback
-    ? callbackOrError
-    : maybeError) as SnapshotErrorCallback | undefined;
   let currentSubId = nextSubId();
   const port = target.port;
   const activity = beginWorkerFirestoreActivity(target, 'onSnapshot', 'subscription', owners);
@@ -206,9 +255,7 @@ export function onSnapshot(
         decoded = makeSnapshot(raw, port, target.converter, baseline);
       } catch (error) {
         stop();
-        const hasErrorCallback = errorCallback !== undefined;
-        if (hasErrorCallback) errorCallback(error);
-        else console.error('pyric/firestore: Uncaught Error in snapshot listener:', error);
+        reportError(error);
         return;
       }
       // An unchanged re-established listener delivers nothing.
@@ -218,9 +265,11 @@ export function onSnapshot(
       // listener id, immediately before the application's callback runs.
       const result = raw as { usage?: UsageEvidence };
       activity.delivered(snapshot, result.usage);
-      deliverWithRegions(activity.id, () => callback(snapshot));
+      const deliver = callback;
+      const hasNext = deliver !== undefined;
+      if (hasNext) deliverWithRegions(activity.id, () => deliver(snapshot));
     },
-    error: (error: unknown) => { activity.fail(); errorCallback?.(error); },
+    error: (error: unknown) => { activity.fail(); reportError(error); },
     close: () => activity.close(),
   };
 

package/src/serve/worker/client/firestore-refs.ts

@@ -19,6 +19,7 @@ import type { ClientDb, DocRefHandle, CollRefHandle, QueryHandle } from './handl
 import { createDocumentReference } from './firestore-reference.js';
 import { FirebaseError } from 'pyric/app';
 import { encodeDocValue, DOC_VALUE_ENCODING } from 'pyric/firestore/internal/value-codec';
+import { normalizeQueryOrders } from 'pyric/firestore/internal/implicit-order';
 import { generateAutoId } from 'pyric/sandbox/internal';
 import type { DocumentData, FieldPath, FirestoreDataConverter, QueryConstraintType } from 'pyric/firestore';
 import { rawClientSnapshotForCursor, type RawCursorSnapshot } from './snapshots.js';
@@ -236,20 +237,9 @@ function resolveQueryConstraints(items: readonly RawConstraintItem[]): QueryCons
     }
   }
 
-  const normalizedOrders = [...explicitOrders];
-  const seen = new Set(normalizedOrders.map((order) => order.field));
-  const lastDirection: 'asc' | 'desc' = explicitOrders.length > 0
-    ? explicitOrders[explicitOrders.length - 1]!.direction
-    : 'asc';
-  for (const field of inequalityFields) {
-    if (field !== KEY_FIELD && !seen.has(field)) {
-      seen.add(field);
-      normalizedOrders.push({ field, direction: lastDirection });
-    }
-  }
-  if (!seen.has(KEY_FIELD)) {
-    normalizedOrders.push({ field: KEY_FIELD, direction: lastDirection });
-  }
+  // One normalization for every plane: inequality fields in field-path
+  // order, then the document key (#1364, FL-4).
+  const normalizedOrders = normalizeQueryOrders(explicitOrders, inequalityFields);
 
   // Place normalized `orderBy` clauses before resolved snapshot cursors so host
   // positional cursor normalization sees every sort slot including `__name__`.

package/src/serve/worker/client/rtdb-connection-lifecycle.ts

@@ -3,6 +3,7 @@ import { validateWritablePath } from 'pyric/database/internal';
 import { nextId } from './core.js';
 import type { ClientPort, ClientRtdb, ClientRtdbInstance, RtdbRefHandle } from './handles.js';
 import { rtdbRpc } from './rtdb-references.js';
+import { validateRtdbPriority, validateRtdbUpdateValues, validateRtdbValue } from './rtdb-value-validation.js';
 
 interface RtdbConnectionState {
   networkEnabled: boolean;
@@ -85,6 +86,7 @@ export class RtdbOnDisconnect {
 
   set(value: unknown): Promise<void> {
     validateWritablePath('OnDisconnect.set', this._path);
+    validateRtdbValue('OnDisconnect.set', value, this._path);
     return rtdbRpc(this._repo, {
       t: 'op', id: nextId(), method: 'rtdb.onDisconnectSet', path: this._path, value,
     }).then(() => undefined);
@@ -92,6 +94,8 @@ export class RtdbOnDisconnect {
 
   setWithPriority(value: unknown, priority: string | number | null): Promise<void> {
     validateWritablePath('OnDisconnect.setWithPriority', this._path);
+    validateRtdbValue('OnDisconnect.setWithPriority', value, this._path);
+    validateRtdbPriority('OnDisconnect.setWithPriority', priority);
     return rtdbRpc(this._repo, {
       t: 'op', id: nextId(), method: 'rtdb.onDisconnectSet', path: this._path, value, priority,
     }).then(() => undefined);
@@ -99,6 +103,7 @@ export class RtdbOnDisconnect {
 
   update(values: Record<string, unknown>): Promise<void> {
     validateWritablePath('OnDisconnect.update', this._path);
+    validateRtdbUpdateValues('OnDisconnect.update', values, this._path);
     return rtdbRpc(this._repo, {
       t: 'op', id: nextId(), method: 'rtdb.onDisconnectUpdate', path: this._path, values,
     }).then(() => undefined);

package/src/serve/worker/client/rtdb-snapshots.ts

@@ -129,17 +129,39 @@ export function makeRtdbSnapshot(
   };
 }
 
+/**
+ * `value` with each `null` array element turned back into a hole. The hosted
+ * transport carries JSON, which writes a hole in `val()`'s sparse array as
+ * `null`; RTDB never stores a `null` child, so every such `null` was a hole
+ * (RT-6, #1371). A structured-clone port keeps holes, and this leaves them.
+ */
+export function restoreArrayHoles(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) {
+    const restored: unknown[] = [];
+    restored.length = value.length;
+    value.forEach((element, index) => {
+      if (element !== null) restored[index] = restoreArrayHoles(element);
+    });
+    return restored;
+  }
+  const restored: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value)) restored[key] = restoreArrayHoles(child);
+  return restored;
+}
+
 export function hydrateRtdbSnapshot(
   refHandle: RtdbRefHandle,
   wire: unknown,
 ): RtdbDataSnapshot {
   const payload = wire as RtdbWireSnapshot;
+  const entries = payload.entries?.map((entry) => ({ ...entry, value: restoreArrayHoles(entry.value) }));
   return makeRtdbSnapshot(
     refHandle,
-    payload.value ?? null,
+    restoreArrayHoles(payload.value ?? null),
     payload.exists,
     payload.priority ?? null,
-    payload.entries,
+    entries,
     payload.exportValue ?? payload.value ?? null,
   );
 }

package/src/serve/worker/client/rtdb-value-validation.ts

@@ -0,0 +1,198 @@
+/**
+ * The SDK's checks on an RTDB write's value, priority and update map, run by
+ * the served client before it sends a frame. Production's SDK throws these
+ * synchronously (`core/util/validation.ts` in `@firebase/database`), and the
+ * texts are its texts. On the Node host the frame is JSON, where NaN and
+ * Infinity become null and an undefined member vanishes, so a value that got
+ * past this point would arrive as a delete (RP-1, #1362).
+ */
+
+const INVALID_KEY = /[[\].#$/\u0000-\u001F\u007F]/;
+const MAX_LEAF_BYTES = 10 * 1024 * 1024;
+const MAX_PATH_BYTES = 768;
+const MAX_PATH_DEPTH = 32;
+const PRIORITY_RULE = 'must be a valid Firebase priority (a string, finite number, server value, or null).';
+
+/** Where in the written value a check is looking, as the SDK's `ValidationPath` tracks it. */
+interface ValidationPath {
+  readonly prefix: string;
+  readonly parts: string[];
+  bytes: number;
+}
+
+function argumentPrefix(fnName: string, argument: string): string {
+  return `${fnName} failed: ${argument} argument `;
+}
+
+function pathSegments(path: string): string[] {
+  return path.split('/').filter((segment) => segment.length > 0);
+}
+
+/** UTF-8 length as the SDK counts it (`stringLength`). */
+function utf8Length(text: string): number {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    const isHighSurrogate = code >= 0xd800 && code <= 0xdbff;
+    if (code < 128) bytes += 1;
+    else if (code < 2048) bytes += 2;
+    else if (isHighSurrogate) { bytes += 4; i++; }
+    else bytes += 3;
+  }
+  return bytes;
+}
+
+function isInvalidJsonNumber(value: unknown): value is number {
+  return typeof value === 'number' && !Number.isFinite(value);
+}
+
+function isValidKey(key: string): boolean {
+  return key.length !== 0 && !INVALID_KEY.test(key);
+}
+
+/**
+ * A server value: the SDK's `{ '.sv': ... }`, or the served client's
+ * `serverTimestamp()` marker, which the host turns into one.
+ */
+function isServerValue(value: unknown): boolean {
+  const isObject = typeof value === 'object' && value !== null;
+  return isObject && (Object.hasOwn(value, '.sv') || Object.hasOwn(value, '__rtdbSentinel'));
+}
+
+function isValidPriority(priority: unknown): boolean {
+  const isFiniteNumber = typeof priority === 'number' && Number.isFinite(priority);
+  return priority === null || typeof priority === 'string' || isFiniteNumber || isServerValue(priority);
+}
+
+function describePath(path: ValidationPath): string {
+  const isAtRoot = path.parts.length === 0;
+  if (isAtRoot) return '';
+  return `in property '${path.parts.join('.')}'`;
+}
+
+function checkPathLimits(path: ValidationPath): void {
+  const isTooLong = path.bytes > MAX_PATH_BYTES;
+  if (isTooLong) throw new Error(`${path.prefix}has a key path longer than ${MAX_PATH_BYTES} bytes (${path.bytes}).`);
+  const isTooDeep = path.parts.length > MAX_PATH_DEPTH;
+  if (isTooDeep) {
+    throw new Error(
+      `${path.prefix}path specified exceeds the maximum depth that can be written (${MAX_PATH_DEPTH}) ` +
+      `or object contains a cycle ${describePath(path)}`,
+    );
+  }
+}
+
+function startPath(prefix: string, segments: string[]): ValidationPath {
+  const bytes = Math.max(1, segments.length) + segments.reduce((sum, part) => sum + utf8Length(part), 0);
+  const path = { prefix, parts: [...segments], bytes };
+  checkPathLimits(path);
+  return path;
+}
+
+function pushPart(path: ValidationPath, part: string): void {
+  const needsSeparator = path.parts.length > 0;
+  if (needsSeparator) path.bytes += 1;
+  path.parts.push(part);
+  path.bytes += utf8Length(part);
+  checkPathLimits(path);
+}
+
+function popPart(path: ValidationPath): void {
+  const last = path.parts.pop() ?? '';
+  path.bytes -= utf8Length(last);
+  const hadSeparator = path.parts.length > 0;
+  if (hadSeparator) path.bytes -= 1;
+}
+
+function checkLeaf(data: unknown, path: ValidationPath): void {
+  const where = describePath(path);
+  if (data === undefined) throw new Error(`${path.prefix}contains undefined ${where}`);
+  if (typeof data === 'function') {
+    throw new Error(`${path.prefix}contains a function ${where} with contents = ${String(data)}`);
+  }
+  if (isInvalidJsonNumber(data)) throw new Error(`${path.prefix}contains ${String(data)} ${where}`);
+  const isLongString = typeof data === 'string' && data.length > MAX_LEAF_BYTES / 3 && utf8Length(data) > MAX_LEAF_BYTES;
+  if (isLongString) {
+    throw new Error(
+      `${path.prefix}contains a string greater than ${MAX_LEAF_BYTES} utf8 bytes ${where} ('${data.substring(0, 50)}...')`,
+    );
+  }
+}
+
+function checkChildren(data: object, path: ValidationPath): void {
+  let hasDotValue = false;
+  let hasActualChild = false;
+  for (const [key, child] of Object.entries(data)) {
+    const isDotValue = key === '.value';
+    const isMetadata = key === '.priority' || key === '.sv';
+    if (isDotValue) hasDotValue = true;
+    else if (!isMetadata) {
+      hasActualChild = true;
+      const isInvalidKey = !isValidKey(key);
+      if (isInvalidKey) {
+        throw new Error(
+          `${path.prefix} contains an invalid key (${key}) ${describePath(path)}.  Keys must be non-empty strings ` +
+          'and can\'t contain ".", "#", "$", "/", "[", or "]"',
+        );
+      }
+    }
+    pushPart(path, key);
+    checkData(child, path);
+    popPart(path);
+  }
+  const mixesDotValue = hasDotValue && hasActualChild;
+  if (mixesDotValue) {
+    throw new Error(`${path.prefix} contains ".value" child ${describePath(path)} in addition to actual children.`);
+  }
+}
+
+/** `validateFirebaseData`: the value and every member under it. */
+function checkData(data: unknown, path: ValidationPath): void {
+  checkLeaf(data, path);
+  const isContainer = typeof data === 'object' && data !== null;
+  if (isContainer) checkChildren(data, path);
+}
+
+/** `validateFirebaseDataArg`: `fnName` writes `value` at `path`; `optional` lets `undefined` through. */
+export function validateRtdbValue(fnName: string, value: unknown, path: string, optional = false): void {
+  const isOmitted = optional && value === undefined;
+  if (isOmitted) return;
+  checkData(value, startPath(argumentPrefix(fnName, 'value'), pathSegments(path)));
+}
+
+/** `validatePriority`: a string, finite number, server value or null. */
+export function validateRtdbPriority(fnName: string, priority: unknown): void {
+  const prefix = argumentPrefix(fnName, 'priority');
+  if (isInvalidJsonNumber(priority)) throw new Error(`${prefix}is ${String(priority)}, but ${PRIORITY_RULE}`);
+  const isInvalid = !isValidPriority(priority);
+  if (isInvalid) throw new Error(`${prefix}${PRIORITY_RULE}`);
+}
+
+/** The SDK's refusal of an update map that is not a plain object. */
+export function updateValuesShapeError(fnName: string): Error {
+  return new Error(`${argumentPrefix(fnName, 'values')} must be an object containing the children to replace.`);
+}
+
+function isUpdateMap(values: unknown): values is Record<string, unknown> {
+  return typeof values === 'object' && values !== null && !Array.isArray(values);
+}
+
+/**
+ * `validateFirebaseMergeDataArg` up to its key-path checks: `values` is an
+ * object, each value is writable at its own path, and a `.priority` entry is
+ * a valid priority. The key paths themselves are `validateUpdatePaths`'s.
+ */
+export function validateRtdbUpdateValues(fnName: string, values: unknown, path: string): asserts values is Record<string, unknown> {
+  const isNotAMap = !isUpdateMap(values);
+  if (isNotAMap) throw updateValuesShapeError(fnName);
+  const prefix = argumentPrefix(fnName, 'values');
+  for (const [key, value] of Object.entries(values)) {
+    const keySegments = pathSegments(key);
+    checkData(value, startPath(prefix, [...pathSegments(path), ...keySegments]));
+    const setsPriority = keySegments.at(-1) === '.priority';
+    const isInvalidPriority = setsPriority && !isValidPriority(value);
+    if (isInvalidPriority) {
+      throw new Error(`${prefix}contains an invalid value for '/${keySegments.join('/')}', which ${PRIORITY_RULE}`);
+    }
+  }
+}