@frontera-sdk/functions 1.52.39 → 1.52.41

package/src/testing.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import type { PropertyCondition, WhereNode } from '@frontera-sdk/blueprint/types'
 import {
   duplicateStepMessage,
   duplicateSubmissionMessage,
@@ -9,11 +10,16 @@ import {
   personConfirmTimeoutRefusal,
   submitOutsideStepMessage,
 } from './messages'
+import { FronteraCallError } from './errors'
+import { validateInputValue } from './inputs'
+import { validateManifest } from './manifest'
 import { asFileHandle, carriesFileHandle } from './runtime-context'
+import { TEST_CONTEXT_CHECK, TEST_CONTEXT_RUN } from './test-check'
 import type {
   ActionSubmission,
   ActionSubmitResult,
   AutomationContext,
+  AutomationManifest,
   FunctionCaller,
   PersonConfirmRequest,
   PersonConfirmResult,
@@ -36,12 +42,18 @@ import type {
  *
  * It enforces what the platform enforces, in the platform's own words: a
  * missing grant and a repeated step name fail here exactly as they fail in
- * production, so a green test means something.
+ * production, so a green test means something. Through a `defineFunction`
+ * handler (`fn.handler(ctx)`) the manifest is checked as a deploy checks it
+ * (an input named `siteId` fails here as it fails `frontera local dev`) and
+ * a stated `input` as the run route checks it.
  *
- * What it does NOT simulate is resumption. In production a handler is re-entered
- * after every step, so code outside a step runs many times; here the handler is
- * called once, straight through. Steps still memoize by name within the run, and
- * everything the handler did is recorded on `calls`.
+ * Resumption is simulated only when asked (`replay: true`). In production a
+ * handler is re-entered after every step, so code outside a step runs many
+ * times and completed steps hand back their stored (JSON) results. By default
+ * the handler is called once, straight through; with `replay` it is run as the
+ * platform runs it, so a read outside a step that a later step changes shows
+ * up here rather than only on the runtime. Everything the handler did is
+ * recorded on `calls`.
  */
 
 /**
@@ -60,10 +72,49 @@ export interface TestCall {
   label: string
   /** Present on a step: how it ended. */
   status?: 'ok' | 'error'
+  /** Present on a Blueprint query: the options it was called with, `{}` when none. */
+  options?: BlueprintQueryOptions
 }
 
+/**
+ * What a Blueprint query answers in a test: the object type's rows (a bare
+ * array, read as one complete page), a `{ rows, hasMore }` answer, which the
+ * query's `where`, `orderBy`, `limit`, `pageToken` and `nearest` are applied
+ * to as the platform applies them, or a function of the query's options for
+ * an answer the rows cannot express (it may return either form too). Any
+ * other shape is refused when queried, naming the object type.
+ */
+export type BlueprintStub =
+  | ReadonlyArray<Record<string, unknown>>
+  | BlueprintQueryResult<never>
+  | BlueprintQueryResult<Record<string, unknown>>
+  | ((
+      options: BlueprintQueryOptions,
+    ) =>
+      | BlueprintQueryResult<Record<string, unknown>>
+      | ReadonlyArray<Record<string, unknown>>
+      | Promise<BlueprintQueryResult<Record<string, unknown>> | ReadonlyArray<Record<string, unknown>>>)
+
 
 export interface TestContextOptions {
+  /**
+   * Run the handler as the platform does: after each step that completes for
+   * the first time (and each `ctx.step.sleep`, top-level `ctx.agent(…).run`
+   * and `ctx.person.confirm`), the handler starts again from the top, and the
+   * completed ones hand back their stored result, as JSON, without running.
+   *
+   * What it catches: code outside a step that reads something a step changes.
+   * The first pass reads the record before the step writes it; the replay
+   * reads it again after, and the handler takes the other branch, exactly as
+   * it does on the runtime. A read outside a step also runs once per step, as
+   * it does there, so `calls` shows each of them.
+   *
+   * Applies through a `defineFunction` handler (`fn.handler(ctx)`), and
+   * through `run(handler)` for a plain handler. `steps` lists each step once,
+   * in the order it first ran. Off by default, so an existing test that counts
+   * the calls made outside its steps keeps its numbers.
+   */
+  replay?: boolean
   runId?: string
   workspaceId?: string
   /** Who asked for the run through an Agent; `null` (no Agent) by default. */
@@ -73,7 +124,10 @@ export interface TestContextOptions {
   /** How the person answers `ctx.person.confirm`: a fixed answer or a function of the request; `unavailable` by default. */
   confirm?: PersonConfirmResult | ((request: PersonConfirmRequest) => PersonConfirmResult)
   /** What the run was started with. Passed through verbatim — a unit test
-   *  states exactly what the handler sees; defaults are `startRun`'s job. */
+   *  states exactly what the handler sees; defaults are `startRun`'s job.
+   *  Run through a `defineFunction` handler, it is checked against the
+   *  manifest's inputs as the run route checks it: an undeclared or
+   *  mistyped field, or a missing required one, fails the call. */
   input?: Record<string, unknown>
   /**
    * The grants the manifest declares.
@@ -108,9 +162,27 @@ export interface TestContextOptions {
    * a branch worth testing.
    */
   conversation?: ConversationTranscript | null
-  /** Rows per object type. An unstubbed type returns no rows, which is a real
-   *  answer and usually the branch worth testing. */
-  blueprint?: Record<string, BlueprintQueryResult<never> | BlueprintQueryResult<Record<string, unknown>>>
+  /**
+   * Rows per object type (`{ Site: [row, …] }` or `{ Site: { rows, hasMore } }`),
+   * or a function of the query's options. A query's
+   * `where`, `orderBy`, `limit`, `pageToken` and `nearest` narrow the rows
+   * the way the platform's query does (three-valued: a NULL property matches
+   * neither a condition nor its `not`; `$now` and `$now-4h` read at `now`), so
+   * a handler that filters on the server is tested filtering. A query the
+   * platform refuses for its shape is refused here in its words, whatever the
+   * stub: a `nearest` without a `nearby` or `withinBbox` on the same location
+   * (through `and` only), a malformed condition, a radius or point out of
+   * range. What needs the object type's catalog is refused where the stubbed
+   * rows show it: a typo of a stubbed property, a geo operator on a property
+   * whose values are not points, a comparison on one whose values are. `select` is not applied: every stubbed
+   * property comes back. An unstubbed type returns no rows, which is a real
+   * answer and usually the branch worth testing.
+   */
+  blueprint?: Record<string, BlueprintStub>
+  /** "Now" for a `dateRange` condition (default: the real time). */
+  now?: Date
+  /** The timezone a `dateRange` without one resolves in (default UTC). */
+  timezone?: string
   /**
    * Per-apiName Action outcomes. An unstubbed Action throws rather than
    * answering.
@@ -133,13 +205,113 @@ export interface TestContext {
   /** Step names, in the order they ran. */
   steps: string[]
   logs: Array<{ message: string; data?: Record<string, unknown> }>
+  /**
+   * Run a handler with this context: once, or with `replay`, again from the
+   * top after each step until it returns, as the platform runs it. A
+   * `defineFunction` handler (`fn.handler(ctx)`) does this by itself.
+   */
+  run<T>(handler: (ctx: AutomationContext) => Promise<T> | T): Promise<T>
+  /** How many times the handler was started: 1 without `replay`. */
+  executions: number
+}
+
+/**
+ * The error the platform refuses a `ctx.action.submit` with, for an `actions`
+ * stub to throw: the same `FronteraCallError`, message, `code`, `status` and
+ * `details` a run gets, so a test asserts the branch a handler takes on
+ * `err.code`.
+ *
+ * ```ts
+ * actions: {
+ *   reprioritiseServiceRequest: () => {
+ *     throw actionRefused('ACTION_REQUEST_ALREADY_OPEN', 'Record "SRV-1" already has an open reprioritiseServiceRequest request', {
+ *       details: { openRequest: { requestId: 'req-1', lifecycle: 'awaiting_approval' } },
+ *     })
+ *   },
+ * }
+ * ```
+ *
+ * `status` defaults to 409, the status of most Action refusals; pass the one the
+ * code has (403 for `ACTION_FORBIDDEN`, 404 for `ACTION_NOT_FOUND`) when a test
+ * reads it.
+ */
+export function actionRefused(code: string, message: string, options: { status?: number; details?: unknown } = {}): FronteraCallError {
+  return new FronteraCallError('ctx.action.submit', options.status ?? 409, message, { code, details: options.details })
+}
+
+/** A run that keeps asking for steps without ever returning. */
+const MAX_EXECUTIONS = 10_000
+
+/** A memoized step's answer, as the platform stores it: JSON, or the error it ended with. */
+type Memo = { ok: true; json: string | undefined } | { ok: false; error: unknown }
+
+/** A promise that never settles: what an execution that reached a new step waits on, as the platform abandons it. */
+const PARKED = new Promise<never>(() => {})
+
+/**
+ * Refuse what the platform refuses, before the handler runs: a manifest that
+ * would not deploy (`validateManifest`, the deploy check, so an input named
+ * `siteId` fails here as it fails `frontera local dev`), and an input the
+ * run route would turn away (`validateInputValue`), when the test states one.
+ */
+function checkLikeThePlatform(manifest: AutomationManifest, input: Record<string, unknown> | undefined): void {
+  const deploy = validateManifest(manifest)
+  if (!deploy.valid) throw new Error(`Function "${String(manifest.name)}" would not deploy: ${deploy.errors.join('; ')}`)
+  if (input === undefined) return
+  const run = validateInputValue(manifest.inputs, input)
+  if (!run.ok) throw new Error(`Function "${String(manifest.name)}" would refuse this input: ${run.errors.join('; ')}`)
 }
 
 export function createTestContext(options: TestContextOptions = {}): TestContext {
   const calls: TestCall[] = []
   const steps: string[] = []
   const logs: TestContext['logs'] = []
-  const seenNames = new Set<string>()
+  let seenNames = new Set<string>()
+  const replay = options.replay === true
+  /**
+   * Replay's state. `memo` holds each completed step's answer by name, across
+   * executions; `ordinal` numbers the durable calls that are not named steps
+   * (a top-level agent run, a confirmation), as the runtime names them, per
+   * execution. An execution that completes something new ends there: `fresh`
+   * counts what is still running in it, and `boundary` starts the next one.
+   */
+  const memo = new Map<string, Memo>()
+  let ordinal = { agent: 0, confirm: 0 }
+  let fresh = 0
+  let reachedNew = false
+  let boundary: (() => void) | null = null
+  let executions = 0
+  const settleFresh = () => {
+    fresh--
+    if (fresh === 0 && reachedNew && boundary) boundary()
+  }
+  const recall = <T>(m: Memo): T => {
+    if (!m.ok) throw m.error
+    return (m.json === undefined ? undefined : JSON.parse(m.json)) as T
+  }
+  /**
+   * One durable call under replay: its stored answer when an earlier execution
+   * completed it; else run it, store the answer, and park this execution so
+   * the next one starts from the top. A failure is stored and thrown here, as
+   * the platform hands a failed step's error back to the handler.
+   */
+  const durable = async <T>(key: string, work: () => Promise<T>): Promise<T> => {
+    const known = memo.get(key)
+    if (known) return recall<T>(known)
+    fresh++
+    let value: T
+    try {
+      value = await work()
+    } catch (error) {
+      memo.set(key, { ok: false, error })
+      settleFresh()
+      throw error
+    }
+    memo.set(key, { ok: true, json: value === undefined ? undefined : JSON.stringify(value) })
+    reachedNew = true
+    settleFresh()
+    return PARKED
+  }
   /**
    * Which step the running code is inside.
    *
@@ -174,8 +346,9 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
       async run<T>(name: string, fn: () => Promise<T>): Promise<T> {
         if (seenNames.has(name)) throw new Error(duplicateStepMessage(name))
         seenNames.add(name)
+        if (replay && memo.has(name)) return recall<T>(memo.get(name)!)
         steps.push(name)
-        return await stepScope.run({ stepName: name, submitted: new Set<string>() }, async () => {
+        const body = () => stepScope.run({ stepName: name, submitted: new Set<string>() }, async () => {
           try {
             const out = await fn()
             // Nothing here replays a step, so the handle would keep working in
@@ -188,15 +361,19 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
             throw err
           }
         })
+        return replay ? await durable(name, body) : await body()
       },
 
       async sleep(name: string): Promise<void> {
         if (seenNames.has(name)) throw new Error(duplicateStepMessage(name))
         seenNames.add(name)
+        if (replay && memo.has(name)) return
         steps.push(name)
         // Recorded, never waited: a test suite that really slept out its
         // backoffs would take minutes to say nothing.
         calls.push({ kind: 'step', label: name, status: 'ok' })
+        // A sleep is a checkpoint on the platform: the handler resumes from the top after it.
+        if (replay) await durable(name, async () => undefined)
       },
     },
 
@@ -237,6 +414,17 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
       return {
         async run(prompt: string) {
           requireGrant(`agent:${slug}:run`)
+          // At the top level the platform runs an Agent durably, under steps of its own: a replay
+          // hands back the answer it stored, by the call's place in the run, without asking again.
+          if (replay && !stepScope.getStore()) {
+            const key = `agent:${slug}:${ordinal.agent++}`
+            if (!memo.has(key)) calls.push({ kind: 'agent', label: slug })
+            return await durable(key, async () => {
+              const stub = options.agents?.[slug]
+              if (!stub) throw new Error(`No agent stub for "${slug}". Pass agents: { '${slug}': () => ({ text: '…' }) } to createTestContext.`)
+              return await stub(prompt)
+            })
+          }
           calls.push({ kind: 'agent', label: slug })
           const stub = options.agents?.[slug]
           // Throwing beats answering with an empty string: a test whose agent
@@ -346,14 +534,28 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
     blueprint: {
       async query<T = Record<string, unknown>>(
         objectType: string,
-        _options?: BlueprintQueryOptions,
+        queryOptions?: BlueprintQueryOptions,
       ): Promise<BlueprintQueryResult<T>> {
         requireGrant('blueprint:read')
-        calls.push({ kind: 'blueprint', label: objectType })
+        const asked = queryOptions ?? {}
+        // Refused before it is recorded, stubbed or not: a query the platform
+        // refuses read nothing, and a stub function would otherwise answer it.
+        checkQuery(asked)
+        calls.push({ kind: 'blueprint', label: objectType, options: asked })
         const stub = options.blueprint?.[objectType]
         // Empty is a real answer, and the branch an author most often forgets
         // to test — so this one defaults rather than throwing.
-        return (stub ?? { rows: [], hasMore: false }) as BlueprintQueryResult<T>
+        if (!stub) return { rows: [], hasMore: false } as BlueprintQueryResult<T>
+        if (typeof stub === 'function') return asPlatformAnswers(objectType, asRowSet(objectType, await stub(asked), 'returned')) as BlueprintQueryResult<T>
+        const rowSet = asRowSet(objectType, stub, 'given')
+        return asPlatformAnswers(
+          objectType,
+          applyQuery(objectType, rowSet, asked, {
+            now: options.now ?? new Date(),
+            timezone: options.timezone ?? 'UTC',
+          }),
+          rowSet.objectTypeId,
+        ) as BlueprintQueryResult<T>
       },
     },
 
@@ -361,7 +563,17 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
       async confirm(request) {
         const refused = personConfirmTimeoutRefusal(request.timeoutMinutes)
         if (refused) throw new Error(refused)
-        const answer = typeof options.confirm === 'function' ? options.confirm(request) : (options.confirm ?? 'unavailable')
+        const ask = () => (typeof options.confirm === 'function' ? options.confirm(request) : (options.confirm ?? 'unavailable'))
+        // Asked once and remembered on the platform (its own steps), so a replay gets the same answer.
+        if (replay && !stepScope.getStore()) {
+          const key = `person.confirm:${ordinal.confirm++}`
+          return await durable(key, async () => {
+            const answer = ask()
+            calls.push({ kind: 'person', label: answer })
+            return answer
+          })
+        }
+        const answer = ask()
         calls.push({ kind: 'person', label: answer })
         return answer
       },
@@ -376,5 +588,654 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
     },
   }
 
-  return { ctx, calls, steps, logs }
+  // `defineFunction`'s handler calls this before the author's code: what the
+  // platform refuses at deploy (the manifest) and at the run route (the
+  // input) is refused here, in the platform's own words.
+  Object.defineProperty(ctx, TEST_CONTEXT_CHECK, {
+    value: (manifest: AutomationManifest) => checkLikeThePlatform(manifest, options.input),
+    enumerable: false,
+  })
+
+  /**
+   * Run the handler: once, or under `replay` one execution after another
+   * until one returns. An execution ends when everything new it started has
+   * completed (its steps park, as the platform abandons that execution); the
+   * next starts from the top with a fresh set of step names.
+   */
+  const run = async <T>(handler: (ctx: AutomationContext) => Promise<T> | T): Promise<T> => {
+    if (!replay) {
+      executions++
+      return await handler(ctx)
+    }
+    for (let i = 0; i < MAX_EXECUTIONS; i++) {
+      executions++
+      seenNames = new Set<string>()
+      ordinal = { agent: 0, confirm: 0 }
+      fresh = 0
+      reachedNew = false
+      const next = new Promise<'next'>((resolve) => {
+        boundary = () => resolve('next')
+      })
+      const outcome = await Promise.race([
+        Promise.resolve()
+          .then(() => handler(ctx))
+          .then((value) => ({ value }), (error: unknown) => ({ error, failed: true as const })),
+        next,
+      ])
+      boundary = null
+      if (outcome === 'next') continue
+      if ('failed' in outcome) throw outcome.error
+      return outcome.value
+    }
+    throw new Error(`The handler was started ${MAX_EXECUTIONS} times without returning: does it start a new step on every execution (a step name built from the time, or a random one)?`)
+  }
+  Object.defineProperty(ctx, TEST_CONTEXT_RUN, { value: run, enumerable: false })
+
+  return {
+    ctx,
+    calls,
+    steps,
+    logs,
+    run,
+    get executions() {
+      return executions
+    },
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * The platform's query over stubbed rows
+ *
+ * A port of what the Blueprint query compiles to (`compile.ts`,
+ * `sql-emit.ts`, `geo-location.ts`, `validate.ts` in the service), evaluated
+ * over rows instead of emitted as SQL. Three-valued like SQL: a comparison
+ * with a NULL property is unknown, unknown never matches, and `not` of
+ * unknown is unknown, so `ne` and `notIn` exclude rows where the property is
+ * NULL exactly as the platform does.
+ * ------------------------------------------------------------------ */
+
+type Truth = boolean | null
+
+const DEFAULT_LIMIT = 100
+const MAX_LIMIT = 1000
+const PAGE_PREFIX = 'test-page:'
+const EARTH_RADIUS_METERS = 6_371_008.8
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/
+
+const isNullish = (v: unknown): v is null | undefined => v === null || v === undefined
+
+function timeOf(v: unknown): number | null {
+  if (v instanceof Date) return v.getTime()
+  if (typeof v === 'string' && ISO_DATE.test(v)) {
+    const t = Date.parse(v)
+    return Number.isNaN(t) ? null : t
+  }
+  return null
+}
+
+/** How two non-null values order, as a typed column against a literal; null when they do not compare. */
+function compareValues(a: unknown, b: unknown): number | null {
+  if (typeof a === 'number' || typeof b === 'number') {
+    const x = typeof a === 'number' ? a : typeof a === 'string' && a.trim() !== '' ? Number(a) : NaN
+    const y = typeof b === 'number' ? b : typeof b === 'string' && b.trim() !== '' ? Number(b) : NaN
+    return Number.isNaN(x) || Number.isNaN(y) ? null : x - y
+  }
+  const ta = timeOf(a)
+  const tb = timeOf(b)
+  if (ta !== null && tb !== null) return ta - tb
+  if (typeof a === 'boolean' && typeof b === 'boolean') return Number(a) - Number(b)
+  if (typeof a === 'string' && typeof b === 'string') return a < b ? -1 : a > b ? 1 : 0
+  return JSON.stringify(a) === JSON.stringify(b) ? 0 : null
+}
+
+function compareOp(op: string, v: unknown, value: unknown): Truth {
+  if (isNullish(v) || isNullish(value)) return null
+  const c = compareValues(v, value)
+  if (c === null) return op === 'ne' ? true : op === 'eq' ? false : null
+  switch (op) {
+    case 'eq': return c === 0
+    case 'ne': return c !== 0
+    case 'gt': return c > 0
+    case 'gte': return c >= 0
+    case 'lt': return c < 0
+    case 'lte': return c <= 0
+  }
+  throw new Error(`blueprint query: unknown operator "${op}"`)
+}
+
+function and(values: Truth[]): Truth {
+  if (values.includes(false)) return false
+  return values.includes(null) ? null : true
+}
+
+function or(values: Truth[]): Truth {
+  if (values.includes(true)) return true
+  return values.includes(null) ? null : false
+}
+
+function tzOffsetMs(tz: string, at: Date): number {
+  const dtf = new Intl.DateTimeFormat('en-US', { timeZone: tz, hour12: false, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit' })
+  const p: Record<string, string> = {}
+  for (const part of dtf.formatToParts(at)) p[part.type] = part.value
+  const asUtc = Date.UTC(Number(p.year), Number(p.month) - 1, Number(p.day), p.hour === '24' ? 0 : Number(p.hour), Number(p.minute), Number(p.second))
+  return asUtc - at.getTime()
+}
+
+function zonedMidnightUtc(tz: string, y: number, m: number, d: number): Date {
+  const naive = Date.UTC(y, m - 1, d)
+  const off1 = tzOffsetMs(tz, new Date(naive))
+  const off2 = tzOffsetMs(tz, new Date(naive - off1))
+  return new Date(naive - off2)
+}
+
+/** A date preset as the platform resolves it: an end-exclusive [start, end) window in `timezone`. */
+export function resolveDatePreset(preset: string, timezone: string, now: Date): { start: number; end: number } {
+  let parts: Record<string, string>
+  try {
+    parts = {}
+    for (const part of new Intl.DateTimeFormat('en-US', { timeZone: timezone, year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(now)) parts[part.type] = part.value
+  } catch {
+    throw new Error(`blueprint query: unknown timezone "${timezone}"`)
+  }
+  const y = Number(parts.year)
+  const m = Number(parts.month)
+  const d = Number(parts.day)
+  const at = (yy: number, mm: number, dd: number) => zonedMidnightUtc(timezone, yy, mm, dd).getTime()
+  const tomorrow = at(y, m, d + 1)
+  switch (preset) {
+    case 'TODAY': return { start: at(y, m, d), end: tomorrow }
+    case 'YESTERDAY': return { start: at(y, m, d - 1), end: at(y, m, d) }
+    case 'LAST_7_DAYS': return { start: at(y, m, d - 6), end: tomorrow }
+    case 'LAST_30_DAYS': return { start: at(y, m, d - 29), end: tomorrow }
+    case 'LAST_90_DAYS': return { start: at(y, m, d - 89), end: tomorrow }
+    case 'THIS_MONTH': return { start: at(y, m, 1), end: tomorrow }
+    case 'LAST_MONTH': return { start: at(y, m - 1, 1), end: at(y, m, 1) }
+    case 'THIS_QUARTER': return { start: at(y, Math.floor((m - 1) / 3) * 3 + 1, 1), end: tomorrow }
+    case 'THIS_YEAR': return { start: at(y, 1, 1), end: tomorrow }
+  }
+  throw new Error(`blueprint query: unknown date preset "${preset}"`)
+}
+
+function point(v: unknown): { lat: number; lon: number } | null {
+  if (!v || typeof v !== 'object') return null
+  const { lat, lon } = v as { lat?: unknown; lon?: unknown }
+  return typeof lat === 'number' && typeof lon === 'number' && lat >= -90 && lat <= 90 && lon >= -180 && lon <= 180 ? { lat, lon } : null
+}
+
+/** Metres along the sphere, as the platform's haversine measures them. */
+export function distanceMeters(a: { lat: number; lon: number }, b: { lat: number; lon: number }): number {
+  const rad = (x: number) => (x * Math.PI) / 180
+  const hav = Math.sin(rad(a.lat - b.lat) / 2) ** 2 + Math.cos(rad(b.lat)) * Math.cos(rad(a.lat)) * Math.sin(rad(a.lon - b.lon) / 2) ** 2
+  return 2 * EARTH_RADIUS_METERS * Math.asin(Math.min(1, Math.sqrt(hav)))
+}
+
+function withinBbox(p: { lat: number; lon: number }, box: { west: number; south: number; east: number; north: number }): boolean {
+  if (p.lat < box.south || p.lat > box.north) return false
+  if (box.west > box.east) return p.lon >= box.west || p.lon <= box.east
+  if (p.lon >= box.west && p.lon <= box.east) return true
+  return (box.east === 180 && p.lon === -180) || (box.west === -180 && p.lon === 180)
+}
+
+/* The platform's refusals of a query's shape (`validate.ts`, `compile.ts`, `geo-location.ts`, `relative-now.ts`, `ctx-query.ts`), in its words. */
+
+const MAX_RADIUS_METERS = 20_037_509
+const GEO_OPS = new Set(['nearby', 'withinBbox'])
+const ELEMENT_OPS = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte']
+const DATE_PRESETS = ['TODAY', 'YESTERDAY', 'LAST_7_DAYS', 'LAST_30_DAYS', 'LAST_90_DAYS', 'THIS_MONTH', 'LAST_MONTH', 'THIS_QUARTER', 'THIS_YEAR']
+const RELATIVE_NOW = /^\$now(?:\s*([+-])\s*(\d{1,6})\s*(m|min|h|d|w))?$/i
+const RELATIVE_NOW_HINT = 'write "$now", or "$now" with + or - and a whole number of m (minutes), h, d or w, as in "$now-4h"'
+const UNIT_MS: Record<string, number> = { m: 60_000, min: 60_000, h: 3_600_000, d: 86_400_000, w: 7 * 86_400_000 }
+
+const refuse = (message: string): never => {
+  throw new Error(`blueprint query: ${message}`)
+}
+
+function shown(value: unknown): string {
+  if (typeof value === 'number' || value === undefined) return String(value)
+  let text: string
+  try {
+    text = JSON.stringify(value)
+  } catch {
+    text = String(value)
+  }
+  return text.length > 200 ? `${text.slice(0, 200)}…` : text
+}
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)
+const hasExactKeys = (value: Record<string, unknown>, keys: readonly string[]) => Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key))
+
+function coordinateError(name: string, value: unknown, limit: 90 | 180): string | null {
+  if (typeof value !== 'number') return `"${name}" must be a number, got ${shown(value)}`
+  if (!Number.isFinite(value)) return `"${name}" must be a finite number, got ${value}`
+  if (value < -limit || value > limit) return `"${name}" ${value} is outside [-${limit}, ${limit}]`
+  return null
+}
+
+/** A caller's point as the platform reads one: exactly `lat` and `lon`, finite and in range. */
+function parsePoint(value: unknown, label: string): { lat: number; lon: number } {
+  if (!isPlainObject(value) || !hasExactKeys(value, ['lat', 'lon'])) return refuse(`${label} must be an object with exactly the keys "lat" and "lon", got ${shown(value)}`)
+  const error = coordinateError('lat', value.lat, 90) ?? coordinateError('lon', value.lon, 180)
+  if (error) refuse(`${label} ${error}`)
+  return { lat: value.lat as number, lon: value.lon as number }
+}
+
+function parseBbox(value: unknown, label: string): { west: number; south: number; east: number; north: number } {
+  if (!isPlainObject(value) || !hasExactKeys(value, ['west', 'south', 'east', 'north'])) {
+    return refuse(`${label} must be an object with exactly the keys "west", "south", "east" and "north", got ${shown(value)}`)
+  }
+  const error = coordinateError('west', value.west, 180) ?? coordinateError('south', value.south, 90) ?? coordinateError('east', value.east, 180) ?? coordinateError('north', value.north, 90)
+  if (error) refuse(`${label} ${error}`)
+  const box = value as { west: number; south: number; east: number; north: number }
+  if (box.south > box.north) refuse(`${label} "south" ${box.south} is north of "north" ${box.north}`)
+  return box
+}
+
+function parseRadius(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > MAX_RADIUS_METERS) {
+    return refuse(`${label} must be a number greater than 0 and at most ${MAX_RADIUS_METERS}, got ${shown(value)}`)
+  }
+  return value
+}
+
+const looksLikeRelativeNow = (value: unknown): value is string => typeof value === 'string' && /^\s*\$now/i.test(value)
+
+/** The instant a relative now (`$now`, `$now-4h`) names, or null when the value is not one or is malformed. */
+function relativeNowInstant(value: unknown, now: Date): Date | null {
+  if (typeof value !== 'string') return null
+  const match = RELATIVE_NOW.exec(value.trim())
+  if (!match) return null
+  const [, sign, amount, unit] = match
+  if (!sign) return new Date(now.getTime())
+  const delta = Number(amount) * UNIT_MS[unit!.toLowerCase()]!
+  return new Date(now.getTime() + (sign === '-' ? -delta : delta))
+}
+
+/** A condition value with a relative now replaced by its ISO instant, read at the query's "now". */
+function resolveRelativeNow(value: unknown, now: Date): unknown {
+  const instant = relativeNowInstant(value, now)
+  return instant ? instant.toISOString() : value
+}
+
+const isCondition = (node: WhereNode): node is PropertyCondition => typeof (node as PropertyCondition).property === 'string'
+
+/**
+ * Refuse a `where` the platform refuses for its shape alone. What needs the
+ * object type's catalog (an operator its property type does not take, a relative
+ * now on a property that is not a time) is refused where the stubbed rows show
+ * it: see `checkAgainstRows`.
+ */
+export function checkWhere(where: WhereNode): void {
+  if (!isPlainObject(where)) refuse('where node must be a JSON object (a condition or and/or/not combinator)')
+  if (!isCondition(where)) {
+    if ('and' in where && Array.isArray(where.and)) return where.and.forEach(checkWhere)
+    if ('or' in where && Array.isArray(where.or)) return where.or.forEach(checkWhere)
+    if ('not' in where) return checkWhere(where.not)
+    return refuse('where node must be a condition or and/or/not')
+  }
+  const c = where
+  if (c.radiusMeters !== undefined && c.op !== 'nearby') refuse(`"${c.op}" on "${c.property}": radiusMeters applies to "nearby" only`)
+  const label = `"${c.op}" on "${c.property}":`
+  switch (c.op) {
+    case 'nearby':
+    case 'withinBbox':
+      if (c.elementWhere !== undefined) refuse(`${label} a location has no elements; elementWhere applies to arrayAny only`)
+      if (c.op === 'nearby') {
+        parsePoint(c.value, `${label} value`)
+        parseRadius(c.radiusMeters, `${label} radiusMeters`)
+      } else {
+        parseBbox(c.value, `${label} value`)
+      }
+      return
+    case 'dateRange':
+      if (!c.preset) refuse('"dateRange" requires a preset')
+      if (!DATE_PRESETS.includes(c.preset as string)) refuse(`unknown date preset "${c.preset}"`)
+      return
+    case 'arrayAny':
+      if (!Array.isArray(c.elementWhere) || c.elementWhere.length === 0) refuse('"arrayAny" requires a non-empty elementWhere array')
+      for (const e of c.elementWhere!) {
+        if (!isPlainObject(e)) refuse('each element condition must be a JSON object')
+        if (!ELEMENT_OPS.includes(e.op)) refuse(`element operator "${e.op}" is not valid; expected one of ${ELEMENT_OPS.join(', ')}`)
+      }
+      return
+    case 'isNull':
+    case 'isNotNull':
+    case 'eq':
+    case 'ne':
+    case 'gt':
+    case 'gte':
+    case 'lt':
+    case 'lte':
+    case 'in':
+    case 'notIn':
+    case 'between':
+    case 'contains':
+    case 'startsWith':
+      break
+    default:
+      refuse(`unknown operator "${(c as { op?: unknown }).op}"`)
+  }
+  if (c.op === 'between' && (!Array.isArray(c.values) || c.values.length !== 2)) refuse('"between" requires exactly two values')
+  for (const value of [c.value, ...(Array.isArray(c.values) ? c.values : [])]) {
+    if (looksLikeRelativeNow(value) && !relativeNowInstant(value, new Date(0))) refuse(`"${value}" on "${c.property}" is not a relative now: ${RELATIVE_NOW_HINT}`)
+  }
+  if ((c.op === 'in' || c.op === 'notIn') && (!Array.isArray(c.values) || c.values.length === 0)) refuse(`"${c.op}" requires a non-empty values array`)
+  if ((c.op === 'contains' || c.op === 'startsWith') && typeof c.value !== 'string') refuse(`"${c.op}" requires a string value`)
+}
+
+/** Through `and` only, as the platform reads "the object set is bounded by a geo filter on this location". */
+function whereBoundsLocation(where: WhereNode, property: string): boolean {
+  if (isCondition(where)) return where.property === property && (where.op === 'nearby' || where.op === 'withinBbox')
+  return 'and' in where && where.and.some((node) => whereBoundsLocation(node, property))
+}
+
+/**
+ * Refuse a query the platform refuses before it reads a row, in its words:
+ * the removed `filter`, a malformed `where`, a `nearest` without a geo filter
+ * on its location (or with `orderBy`, or extra keys), a `limit` that is not a
+ * whole number. Runs for every query, stubbed or not, and before it is recorded
+ * in `calls`, because a refused query read nothing.
+ */
+export function checkQuery(options: BlueprintQueryOptions): void {
+  if ((options as { filter?: unknown }).filter !== undefined) {
+    refuse('`filter` is gone: it was a placeholder on the stubbed endpoint and never filtered anything. '
+      + 'Use `where` with the Blueprint filter DSL — e.g. { where: { property: "status", op: "eq", value: "open" } }.')
+  }
+  if (options.where !== undefined) checkWhere(options.where)
+  if (options.limit !== undefined) {
+    const pageSize = Math.min(Math.max(options.limit, 1), MAX_LIMIT)
+    if (!Number.isInteger(pageSize)) refuse(`pageSize must be an integer 1..${MAX_LIMIT}`)
+  }
+  if (options.nearest === undefined) return
+  const nearest = options.nearest as unknown
+  if (!isPlainObject(nearest) || typeof nearest.property !== 'string') {
+    refuse('"nearest" must be an object { property: "<location apiName>", from: { lat, lon } }')
+  }
+  const asked = nearest as Record<string, unknown>
+  if (!hasExactKeys(asked, ['property', 'from'])) {
+    const extra = Object.keys(asked).filter((key) => key !== 'property' && key !== 'from')
+    refuse(extra.length > 0 ? `"nearest" takes only "property" and "from"; remove ${extra.map((key) => `"${key}"`).join(', ')}` : '"nearest" needs "from": { lat, lon }')
+  }
+  const property = asked.property as string
+  const from = parsePoint(asked.from, '"nearest.from"')
+  if (options.orderBy && options.orderBy.length > 0) {
+    refuse('"nearest" orders the rows by distance, closest first, with the primary key breaking ties; it cannot be combined with "orderBy". Send one or the other.')
+  }
+  if (!options.where || !whereBoundsLocation(options.where, property)) {
+    refuse(`"nearest" on "${property}" needs a "nearby" or "withinBbox" condition on "${property}" in the object set, `
+      + 'outside any "or" or "not" — for example '
+      + `{ "property": "${property}", "op": "nearby", "value": { "lat": ${from.lat}, "lon": ${from.lon} }, "radiusMeters": 5000 }`)
+  }
+}
+
+function condition(c: PropertyCondition, row: Record<string, unknown>, env: { now: Date; timezone: string }): Truth {
+  const v = row[c.property]
+  const value = resolveRelativeNow(c.value, env.now)
+  const values = Array.isArray(c.values) ? c.values.map((x) => resolveRelativeNow(x, env.now)) : []
+  switch (c.op) {
+    case 'isNull': return isNullish(v)
+    case 'isNotNull': return !isNullish(v)
+    case 'eq':
+    case 'ne':
+    case 'gt':
+    case 'gte':
+    case 'lt':
+    case 'lte':
+      return compareOp(c.op, v, value)
+    case 'in':
+    case 'notIn': {
+      if (isNullish(v)) return null
+      const found = or(values.map((x) => compareOp('eq', v, x)))
+      return c.op === 'in' ? found : found === null ? null : !found
+    }
+    case 'between':
+      return and([compareOp('gte', v, values[0]), compareOp('lte', v, values[1])])
+    case 'contains':
+    case 'startsWith': {
+      // ILIKE: case-insensitive, the value taken literally.
+      if (isNullish(v)) return null
+      const text = String(v).toLowerCase()
+      const needle = String(value).toLowerCase()
+      return c.op === 'contains' ? text.includes(needle) : text.startsWith(needle)
+    }
+    case 'dateRange': {
+      const { start, end } = resolveDatePreset(c.preset!, c.timezone ?? env.timezone, env.now)
+      if (isNullish(v)) return null
+      const t = timeOf(v)
+      return t === null ? null : t >= start && t < end
+    }
+    case 'arrayAny': {
+      if (isNullish(v)) return null
+      if (!Array.isArray(v)) throw new Error(`blueprint query: "arrayAny" only applies to an array property; "${c.property}" is not one in the stubbed rows`)
+      return v.some((element) => and(c.elementWhere!.map((e) => compareOp(e.op, e.field ? (element as Record<string, unknown> | null)?.[e.field] : element, e.value))) === true)
+    }
+    case 'nearby': {
+      const at = point(v)
+      return at ? distanceMeters(at, c.value as { lat: number; lon: number }) <= c.radiusMeters! : null
+    }
+    case 'withinBbox': {
+      const at = point(v)
+      return at ? withinBbox(at, c.value as { west: number; south: number; east: number; north: number }) : null
+    }
+  }
+  throw new Error(`blueprint query: unknown operator "${(c as { op?: unknown }).op}"`)
+}
+
+/** Two names one or two edits apart (`stauts`, `status`), case aside: a typo, not another field. */
+function nearMiss(a: string, b: string): boolean {
+  const x = a.toLowerCase()
+  const y = b.toLowerCase()
+  if (x === y) return true
+  if (Math.abs(x.length - y.length) > 2 || Math.min(x.length, y.length) < 4) return false
+  // Optimal string alignment distance, capped at 2: a swap of two letters is one edit.
+  const d: number[][] = Array.from({ length: x.length + 1 }, (_, i) => Array.from({ length: y.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)))
+  for (let i = 1; i <= x.length; i++) {
+    for (let j = 1; j <= y.length; j++) {
+      const cost = x[i - 1] === y[j - 1] ? 0 : 1
+      d[i]![j] = Math.min(d[i - 1]![j]! + 1, d[i]![j - 1]! + 1, d[i - 1]![j - 1]! + cost)
+      if (i > 1 && j > 1 && x[i - 1] === y[j - 2] && x[i - 2] === y[j - 1]) d[i]![j] = Math.min(d[i]![j]!, d[i - 2]![j - 2]! + 1)
+    }
+  }
+  return d[x.length]![y.length]! <= 2
+}
+
+function properties(node: WhereNode, into: Set<string> = new Set()): Set<string> {
+  if ('and' in node) node.and.forEach((n) => properties(n, into))
+  else if ('or' in node) node.or.forEach((n) => properties(n, into))
+  else if ('not' in node) properties(node.not, into)
+  else into.add(node.property)
+  return into
+}
+
+/** Whether a row matches a `where`, in the platform's three-valued logic: true, false, or unknown (null). */
+export function matchesWhere(node: WhereNode, row: Record<string, unknown>, env: { now?: Date; timezone?: string } = {}): Truth {
+  checkWhere(node)
+  return evaluateWhere(node, row, env)
+}
+
+function evaluateWhere(node: WhereNode, row: Record<string, unknown>, env: { now?: Date; timezone?: string }): Truth {
+  const e = { now: env.now ?? new Date(), timezone: env.timezone ?? 'UTC' }
+  const walk = (n: WhereNode): Truth => {
+    if ('and' in n) return and(n.and.map(walk))
+    if ('or' in n) return or(n.or.map(walk))
+    if ('not' in n) {
+      const inner = walk(n.not)
+      return inner === null ? null : !inner
+    }
+    return condition(n, row, e)
+  }
+  return walk(node)
+}
+
+/** NULL sorts as the largest value: last ascending, first descending, as the platform pages. */
+function orderRows(rows: Array<Record<string, unknown>>, orderBy: NonNullable<BlueprintQueryOptions['orderBy']>): Array<Record<string, unknown>> {
+  return rows
+    .map((row, i) => ({ row, i }))
+    .sort((a, b) => {
+      for (const { property, dir } of orderBy) {
+        const x = a.row[property]
+        const y = b.row[property]
+        const sign = dir === 'desc' ? -1 : 1
+        if (isNullish(x) && isNullish(y)) continue
+        if (isNullish(x)) return sign
+        if (isNullish(y)) return -sign
+        const c = compareValues(x, y) ?? 0
+        if (c !== 0) return c * sign
+      }
+      return a.i - b.i
+    })
+    .map(({ row }) => row)
+}
+
+/** The object type id a stub that names none answers with: stable per object type, and plainly a test's. */
+export function testObjectTypeId(objectType: string): string {
+  return `test-object-type:${objectType}`
+}
+
+/**
+ * A stub as the answer it stands for: a bare array of rows is one complete
+ * page (`{ rows, hasMore: false }`); a `{ rows, hasMore }` answer is used as
+ * written. Anything else is refused, so a mistyped stub fails the test instead
+ * of answering "no rows" — which is a real answer, and the branch a wrong
+ * shape would silently test.
+ */
+export function asRowSet(
+  objectType: string,
+  stub: unknown,
+  how: 'given' | 'returned' = 'given',
+): BlueprintQueryResult<Record<string, unknown>> {
+  const where = how === 'given' ? `The blueprint stub for ${objectType}` : `The blueprint stub function for ${objectType} returned a value that`
+  const fix = 'Give its rows as an array (`{ ' + objectType + ': [row, …] }`), a `{ rows: [row, …], hasMore: false }` answer, or a function of the query\'s options that returns one.'
+  const checkRows = (rows: readonly unknown[]) => {
+    const bad = rows.findIndex((row) => row === null || typeof row !== 'object' || Array.isArray(row))
+    if (bad >= 0) throw new Error(`${where} has a row ${bad} that is not an object (${describeShape(rows[bad])}). ${fix}`)
+  }
+  if (Array.isArray(stub)) {
+    checkRows(stub)
+    return { rows: stub as Array<Record<string, unknown>>, hasMore: false }
+  }
+  if (stub === null || typeof stub !== 'object') throw new Error(`${where} is ${describeShape(stub)}, not rows. ${fix}`)
+  const answer = stub as Record<string, unknown>
+  if (!('rows' in answer)) {
+    const keys = Object.keys(answer)
+    throw new Error(`${where} has no "rows"${keys.length ? ` (it has ${keys.map((k) => `"${k}"`).join(', ')})` : ' (it is empty)'}. ${fix}`)
+  }
+  if (!Array.isArray(answer.rows)) throw new Error(`${where} has "rows" that is ${describeShape(answer.rows)}, not an array. ${fix}`)
+  checkRows(answer.rows)
+  if ('hasMore' in answer && typeof answer.hasMore !== 'boolean') throw new Error(`${where} has "hasMore" that is ${describeShape(answer.hasMore)}, not true or false. ${fix}`)
+  return { ...(answer as unknown as BlueprintQueryResult<Record<string, unknown>>), hasMore: answer.hasMore === true }
+}
+
+function describeShape(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'an array'
+  if (typeof value === 'object') return 'an object'
+  if (typeof value === 'string') return 'a string'
+  return `${typeof value === 'undefined' ? 'undefined' : `a ${typeof value}`}`
+}
+
+/**
+ * A query's answer as the platform shapes it, so \`subjectOf\` works in a
+ * test: the object type's id whenever rows came back (the stub's own, else
+ * \`testObjectTypeId\`), and on each row \`_meta: { recordVersion }\` (the
+ * row's own \`_meta\` when the stub gives one, \`null\` included for a row
+ * with no version; else \`0\`, as the platform answers for a record nobody
+ * has edited). The stub itself is never changed.
+ */
+export function asPlatformAnswers(
+  objectType: string,
+  result: BlueprintQueryResult<Record<string, unknown>>,
+  stubObjectTypeId?: string,
+): BlueprintQueryResult<Record<string, unknown>> {
+  const rows = (result.rows ?? []).map((row) => (row && typeof row === 'object' && !('_meta' in row) ? { ...row, _meta: { recordVersion: 0 } } : row))
+  const objectTypeId = result.objectTypeId ?? stubObjectTypeId ?? (rows.length ? testObjectTypeId(objectType) : undefined)
+  return { ...result, rows, ...(objectTypeId ? { objectTypeId } : {}) }
+}
+
+/**
+ * What the platform refuses against the object type's catalog, refused where
+ * the stubbed rows show it. A stub lists only the fields a test cares about, so
+ * a property no row carries is read as empty (null, as an unset field is), unless
+ * it is one letter or two away from one the rows do carry: then it is a typo,
+ * refused as the platform refuses an unknown property. A property whose stubbed
+ * values are points is a location, and one whose values are something else is
+ * not, which settles which operators it takes.
+ */
+function checkAgainstRows(objectType: string, rows: ReadonlyArray<Record<string, unknown>>, options: BlueprintQueryOptions): void {
+  if (!rows.length) return
+  const carried = new Set(rows.flatMap((row) => (row && typeof row === 'object' ? Object.keys(row) : [])))
+  const named = new Set<string>([
+    ...(options.where ? properties(options.where) : []),
+    ...(options.orderBy ?? []).map((o) => o.property),
+    ...(options.select ?? []),
+    ...(options.nearest ? [options.nearest.property] : []),
+  ])
+  for (const property of named) {
+    if (carried.has(property)) continue
+    const near = [...carried].find((name) => name !== '_meta' && nearMiss(property, name))
+    if (near) {
+      throw new Error(`blueprint query on ${objectType}: no stubbed row has the property "${property}" (did you mean "${near}"?). The platform refuses an unknown property; if it exists, give the rows a value for it (null when it has none).`)
+    }
+  }
+  // true: every stubbed value is a point; false: some value is not one; undefined: the rows say nothing.
+  const isLocation = (property: string): boolean | undefined => {
+    const values = rows.map((row) => row[property]).filter((v) => !isNullish(v))
+    if (!values.length) return undefined
+    return values.every((v) => point(v) !== null && isPlainObject(v) && hasExactKeys(v, ['lat', 'lon']))
+  }
+  const walk = (node: WhereNode): void => {
+    if ('and' in node) return node.and.forEach(walk)
+    if ('or' in node) return node.or.forEach(walk)
+    if ('not' in node) return walk(node.not)
+    const location = isLocation(node.property)
+    if (GEO_OPS.has(node.op) && location === false) {
+      refuse(`"${node.op}" only applies to a location property; "${node.property}" on ${objectType} is not a location in the stubbed rows`)
+    }
+    if (location === true && !GEO_OPS.has(node.op) && node.op !== 'isNull' && node.op !== 'isNotNull') {
+      refuse(`operator "${node.op}" is not valid for location "${node.property}" on ${objectType}; use nearby, withinBbox, isNull or isNotNull`)
+    }
+  }
+  if (options.where) walk(options.where)
+  if (options.nearest && isLocation(options.nearest.property) === false) {
+    refuse(`"nearest" only applies to a location property; "${options.nearest.property}" on ${objectType} is not a location in the stubbed rows`)
+  }
+}
+
+/** A stubbed row set, queried. */
+export function applyQuery(
+  objectType: string,
+  stub: BlueprintQueryResult<Record<string, unknown>>,
+  options: BlueprintQueryOptions,
+  env: { now: Date; timezone: string },
+): BlueprintQueryResult<Record<string, unknown>> {
+  checkQuery(options)
+  const shaped = options.where !== undefined || options.orderBy !== undefined || options.limit !== undefined || options.pageToken !== undefined || options.nearest !== undefined
+  // A query that asks for nothing gets the stub as it was written.
+  if (!shaped) return stub
+  const all = stub.rows ?? []
+  checkAgainstRows(objectType, all, options)
+  let rows = options.where ? all.filter((row) => evaluateWhere(options.where!, row, env) === true) : [...all]
+  if (options.nearest) {
+    const from = options.nearest.from as { lat: number; lon: number }
+    const property = options.nearest.property
+    rows = rows
+      .map((row) => ({ row, at: point(row[property]) }))
+      .filter((r): r is { row: Record<string, unknown>; at: { lat: number; lon: number } } => r.at !== null)
+      .map(({ row, at }) => ({ ...row, _distanceMeters: distanceMeters(at, from) }))
+      .sort((a, b) => (a._distanceMeters as number) - (b._distanceMeters as number))
+  } else if (options.orderBy?.length) {
+    rows = orderRows(rows, options.orderBy)
+  }
+  const limit = Math.min(Math.max(Math.trunc(options.limit ?? DEFAULT_LIMIT), 1), MAX_LIMIT)
+  let offset = 0
+  if (options.pageToken !== undefined) {
+    if (!options.pageToken.startsWith(PAGE_PREFIX) || !/^\d+$/.test(options.pageToken.slice(PAGE_PREFIX.length))) {
+      throw new Error(`blueprint query on ${objectType}: pageToken "${options.pageToken}" was not returned by this test context. Pass the previous result's nextPageToken, or stub the object type with a function of the query's options.`)
+    }
+    offset = Number(options.pageToken.slice(PAGE_PREFIX.length))
+  }
+  const page = rows.slice(offset, offset + limit)
+  const more = offset + limit < rows.length
+  // A stub that says it is one page of more keeps saying so on its last page.
+  if (more) return { rows: page, hasMore: true, nextPageToken: `${PAGE_PREFIX}${offset + limit}` }
+  return stub.hasMore ? { rows: page, hasMore: true, ...(stub.nextPageToken ? { nextPageToken: stub.nextPageToken } : {}) } : { rows: page, hasMore: false }
 }