on-zero 0.7.10 → 0.8.0

package/{readme.md → README.md}

@@ -14,8 +14,8 @@ it's what we use for our [takeout stack](https://takeout.tamagui.dev).
 
 on-zero tries to bring Rails-like structure and DRY code to Zero + React.
 
-it works with vanilla Zero and `zero-cache`. there is also a separate integration
-for Orez, our custom Rust sync engine. Orez-only setup and APIs are labeled below.
+it uses vanilla Zero and `zero-cache` by default. an experimental Orez Lite path
+is noted separately at the end of setup.
 
 it provides a few things:
 
@@ -27,25 +27,23 @@ it provides a few things:
 
 plus various hooks and helpers for react integration.
 
-mutations live in `mutations/` with their permissions. queries are just
-functions that use a global `zql` builder. schema is derived from drizzle.
+each namespace is either one file exporting its queries and mutations, or a
+folder with `queries.ts` and `mutations.ts`. queries use the global `zql`
+builder. schema is derived from drizzle.
 
 ## queries
 
 write plain functions. they become synced queries automatically.
 
 ```ts
-// src/data/queries/notification.ts
+// src/data/notification/queries.ts
 import { zql, serverWhere } from 'on-zero'
 
 const permission = serverWhere('notification', (q, auth) => {
   return q.cmp('userId', auth?.id || '')
 })
 
-export const latestNotifications = (props: {
-  userId: string
-  serverId: string
-}) => {
+export const latestNotifications = (props: { userId: string; serverId: string }) => {
   return zql.notification
     .where(permission)
     .where('userId', props.userId)
@@ -78,10 +76,8 @@ const permission = serverWhere('channel', (q, auth) => {
     q.cmp('deleted', '!=', true),
     q.or(
       q.cmp('private', false),
-      q.exists('role', (r) =>
-        r.whereExists('member', (m) => m.where('id', auth?.id)),
-      ),
-    ),
+      q.exists('role', (r) => r.whereExists('member', (m) => m.where('id', auth?.id)))
+    )
   )
 })
 ```
@@ -103,7 +99,7 @@ mutations co-locate permissions and mutation handlers in one file. schema is
 derived from drizzle — no need to define it here.
 
 ```ts
-// src/data/mutations/message.ts
+// src/data/message/mutations.ts
 import { ensureLoggedIn, mutations, serverWhere } from 'on-zero'
 
 const permissions = serverWhere('message', (q, auth) => {
@@ -114,7 +110,7 @@ const permissions = serverWhere('message', (q, auth) => {
 export const mutate = mutations('message', permissions, {
   async send(
     ctx,
-    props: { id: string; content: string; channelId: string; createdAt: number },
+    props: { id: string; content: string; channelId: string; createdAt: number }
   ) {
     const auth = ensureLoggedIn()
 
@@ -180,7 +176,7 @@ export const permissions = serverWhere('channel', (q, auth) => {
 
   return q.or(
     q.cmp('public', true),
-    q.exists('members', (m) => m.where('userId', auth?.id)),
+    q.exists('members', (m) => m.where('userId', auth?.id))
   )
 })
 ```
@@ -191,7 +187,7 @@ server-side - on the client they automatically pass.
 **for queries:** define permissions inline as a constant in query files:
 
 ```ts
-// src/data/queries/channel.ts
+// src/data/channel/queries.ts
 const permission = serverWhere('channel', (q, auth) => {
   return q.cmp('userId', auth?.id || '')
 })
@@ -204,7 +200,7 @@ export const myChannels = () => {
 **for mutations:** define permissions in mutation files for CRUD operations:
 
 ```ts
-// src/data/mutations/message.ts
+// src/data/message/mutations.ts
 const permissions = serverWhere('message', (q, auth) => {
   return q.cmp('authorId', auth?.id || '')
 })
@@ -239,8 +235,9 @@ type RelatedToServer = 'role' | 'channel' | 'message'
 export const hasServerAdminPermission = serverWhere<RelatedToServer>((_, auth) =>
   _.exists('server', (q) =>
     q.whereExists('role', (r) =>
-      r.where('canAdmin', true)
-       .whereExists('member', (m) => m.where('id', auth?.id || ''))
+      r
+        .where('canAdmin', true)
+        .whereExists('member', (m) => m.where('id', auth?.id || ''))
     )
   )
 )
@@ -289,9 +286,7 @@ use in queries:
 import { hasChannelReadPermission } from '../where/channel'
 
 export const channelMessages = (props: { channelId: string }) => {
-  return zql.message
-    .where(hasChannelReadPermission)
-    .where('channelId', props.channelId)
+  return zql.message.where(hasChannelReadPermission).where('channelId', props.channelId)
 }
 ```
 
@@ -311,7 +306,7 @@ export default {
   plugins: [
     onZeroPlugin(),
     // ... other plugins
-  ]
+  ],
 }
 ```
 
@@ -356,8 +351,7 @@ generates all files needed to connect your mutations and queries:
 
 **options:**
 
-- `dir` - base directory containing `mutations/` and `queries/` folders
-  (default: `src/data`)
+- `dir` - base directory containing namespace files/folders (default: `src/data`)
 - `--watch` - watch for changes and regenerate automatically
 - `--after` - command to run after generation completes
 - `--force` - ignore cached inputs and regenerate all outputs
@@ -398,7 +392,7 @@ export type ChannelUpdate = Partial<Channel> & Pick<Channel, 'id'>
 ```ts
 import * as v from 'valibot'
 import { syncedQuery } from '@rocicorp/zero'
-import * as messageQueries from '../queries/message'
+import * as messageQueries from '../message/queries'
 
 export const latestMessages = syncedQuery(
   'latestMessages',
@@ -408,11 +402,11 @@ export const latestMessages = syncedQuery(
         channelId: v.string(),
         limit: v.optional(v.number()),
       }),
-    ]),
+    ])
   ),
   (arg) => {
     return messageQueries.latestMessages(arg)
-  },
+  }
 )
 ```
 
@@ -420,8 +414,8 @@ export const latestMessages = syncedQuery(
 
 the generator:
 
-1. scans `mutations/` for files with `export const mutate`
-2. scans `queries/` for exported arrow functions
+1. discovers namespace files and folders, plus explicit multi-instance config
+2. derives each instance's related-table closure, mutation support tables, and scope
 3. parses TypeScript AST to extract parameter types
 4. converts types to valibot schemas
 5. wraps query functions in `syncedQuery()` with validators
@@ -430,7 +424,7 @@ the generator:
 7. generates `syncedMutations.ts` with valibot validators for mutation args
 
 when using drizzle-zero integration, `schema.ts` is generated from your drizzle
-schema using `generateDrizzleSchemaFile()` — it produces `table()` + 
+schema using `generateDrizzleSchemaFile()` — it produces `table()` +
 `relationships()` + `createSchema()` calls with full type inference.
 
 exports named `permission` are automatically skipped during query generation.
@@ -444,27 +438,37 @@ eliminates duplicate column definitions — drizzle is the single source of trut
 ```ts
 // generate-schema.ts (run at build/dev time)
 import { drizzleZeroConfig } from 'drizzle-zero'
-import { generateDrizzleSchemaFile } from 'on-zero'
-import * as drizzleSchema from './database/schema'
-import { relations } from './database/relations'
-
-const dzSchema = drizzleZeroConfig(
-  { ...drizzleSchema, relations },
-  {
-    tables: {
-      user: true,
-      post: true,
-      comment: true,
-    },
-    suppressDefaultsWarning: true,
-  },
+import {
+  deriveDataMembership,
+  generateDrizzleSchemaFile,
+  generateDrizzleSchemaInputFile,
+} from 'on-zero/generate'
+import * as drizzleSchema from './data/generated/drizzleSchema'
+
+const { allTables } = await deriveDataMembership({ dir: 'src/data' })
+writeFileSync(
+  'src/data/generated/drizzleSchema.ts',
+  await generateDrizzleSchemaInputFile({
+    dir: 'src/data',
+    schemaImportPath: '../../database/schema',
+  })
 )
+const dzSchema = drizzleZeroConfig(drizzleSchema, {
+  tables: Object.fromEntries(allTables.map((table) => [table, true])),
+  suppressDefaultsWarning: true,
+})
 
 // generates a typed schema.ts with createSchema() + relationships()
 const output = generateDrizzleSchemaFile(dzSchema)
 writeFileSync('src/data/generated/schema.ts', output)
 ```
 
+`allTables` includes synced tables plus fileless tables reached through static
+`tx.mutate.<table>` and `tx.query.<table>` accesses in mutation modules and their
+local helpers. these support tables type server pushes but do not become client
+query namespaces or part of `syncTables`. the generated drizzle input filters out
+relations whose source or target is outside `allTables`.
+
 the generated file uses zero's `table()` builder and `relationships()` function,
 giving full type inference for zql queries including nested `.related()` calls.
 
@@ -479,8 +483,7 @@ global schema type — no need to import table builders.
 
 ## setup
 
-there are two server paths. use vanilla Zero unless you have deliberately chosen
-the custom Orez engine. the client factory is shared by both paths:
+the supported setup uses vanilla Zero and `zero-cache`:
 
 ```tsx
 import { createZeroClient } from 'on-zero'
@@ -514,132 +517,59 @@ transport. mount the shared client without a `transport` prop:
 
 configure `zero-cache`, `ZERO_QUERY_URL`, and `ZERO_MUTATE_URL` using the
 standard [Zero installation guide](https://zero.rocicorp.dev/docs/install).
-the executor bindings and client transport in the next section are not part of
-the vanilla Zero path.
-
-### Orez custom Rust engine
-
-Orez is a separate server implementation. it uses the same client factory, but
-passes its own client transport to the provider:
-
-```tsx
-import { createZeroClientTransport } from 'orez/client'
 
-const orezTransport = createZeroClientTransport({
-  pullIntervalMs: 15_000,
-  queryForward: true,
-})
-
-<ProvideZero
-  cacheURL={syncOrigin}
-  transport={orezTransport}
-  userID={user.id}
-  auth={sessionToken}
-  authData={{ id: user.id, email: user.email, role: user.role }}
->
-  <App />
-</ProvideZero>
-```
+### multiple client instances
 
-the following example wires the engine-agnostic on-zero server bindings to
-Orez:
+one page can run several zero clients (e.g. a global control-plane instance
+plus a per-project instance with its own storage key and sync url). add one
+`on-zero.config.ts` at the data root. every instance is explicit; its `dir`
+defaults to the instance key and otherwise resolves relative to the config file.
 
 ```ts
-import { createZeroServerBindings } from 'on-zero/server'
-import {
-  createPostgreSQLApplicationDatabase,
-  createSyncExecutor,
-  handleSyncExecutorPushRequest,
-} from 'orez/sync-executor'
-import { syncedQueries } from '~/data/generated/syncedQueries'
-import { mutationValidators } from '~/data/generated/syncedMutations'
-
-export const zeroBindings = createZeroServerBindings({
-  schema,
-  models,
-  queries: syncedQueries,
-  mutations: mutationValidators,
-  createServerActions: () => ({
-    sendEmail: async (to, subject, body) => { ... }
-  })
-})
+// src/data/on-zero.config.ts
+import { defineConfig } from 'on-zero'
 
-export const zeroExecutor = createSyncExecutor({
-  schema,
-  mutators: zeroBindings.mutators,
-  database: createPostgreSQLApplicationDatabase(pool, {
-    schema,
-    internalSchema: 'zero_0',
-  }),
-  effects: {
-    runBackground: (promise) => host.waitUntil(promise),
-    report: (error) => console.error(error),
+export default defineConfig({
+  instances: {
+    default: { dir: '.', supportTables: ['accountRepo', 'usageLedger'] },
+    project: { dir: './project-data', scope: 'projectId' },
   },
 })
-
-export const zeroServer = zeroBindings.server(zeroExecutor)
-
-app.post('/api/zero/push', async (request) => {
-  const claims = await getClaimsFromRequest(request)
-  return handleSyncExecutorPushRequest({ executor: zeroExecutor, request, claims })
-})
-
-app.post('/api/zero/pull', async (request) => {
-  const authData = await getAuthFromRequest(request)
-  return Response.json(await zeroBindings.transformQueryRequest({ authData, request }))
-})
 ```
 
-Orez owns transactions, CRUD SQL, the client ledger, replay, and effect
-scheduling. on-zero supplies the structural executor seam, mutator registry,
-auth/query helpers, and typed direct-call facade.
+single-instance applications omit the config and keep namespaces directly in
+the data root. multi-instance applications may keep those root namespaces by
+declaring an instance with `dir: '.'`; nested instance directories remain
+independently owned. `instance.ts` and `defineInstance` were removed.
 
-`createZeroServerBindings` is not Orez-specific. it can attach to any server
-implementation of the `ZeroServerExecutor` interface; Orez is the concrete
-executor used in this example.
+generation auto-discovers the config. the cli also accepts its explicit path:
 
-### multiple client instances
+```sh
+on-zero generate ./src/data/on-zero.config.ts
+```
 
-one page can run several zero clients (e.g. a global control-plane instance
-plus a per-project instance with its own storage key and sync url). give each
-a unique `instanceName` and split queries/models so every namespace belongs to
-exactly one instance — duplicate claims throw at create time. then combine
-them into one consumer surface:
+generation derives each instance's queries, models, support tables, and
+sync-table closure and rejects missing or multiply claimed directories,
+duplicate namespaces, missing scope columns, and cross-instance reach.
 
 ```tsx
-import { createZeroClient } from 'on-zero'
-import { combineZeroClients, createZeroClientWithDirectQueries } from 'on-zero/multi'
+import { createZeroClients } from 'on-zero/multi'
+import { instances } from '~/data/generated/instances'
 
-const control = createZeroClientWithDirectQueries({
-  schema,
-  models: controlModels,
-  groupedQueries: controlQueries,
-  instanceName: 'control',
-})
-const project = createZeroClient({
-  schema,
-  models: projectModels,
-  groupedQueries: projectQueries,
-  instanceName: 'project',
-})
+const clients = createZeroClients(instances)
+const control = clients.clients.control
+const project = clients.clients.project
+const ProvideControlZero = clients.providers.control
+const ProvideProjectZero = clients.providers.project
 
 // useQuery/run/preload/getQuery dispatch by the query fn's namespace,
-// zero.mutate.<namespace> dispatches by model namespace; anything unclaimed
-// (and non-mutate zero access like userID) goes to the first client
-export const { useQuery, zero, run, preload, getQuery, zeroEvents } =
-  combineZeroClients(control, project)
-
-// render every instance's provider. NESTING ORDER IS A CONTRACT: the LAST
-// client passed to combineZeroClients (or the `inner` option) must be the
-// INNERMOST provider — zero-react's useQuery resolves the nearest provider's
-// instance from context, so only the inner instance rides that path. all
-// other instances must opt into the context-free direct adapter through
-// createZeroClientWithDirectQueries.
-;<control.ProvideZero cacheURL={controlUrl} userID={user.id}>
-  <project.ProvideZero cacheURL={projectUrl} userID={`${user.id}:${projectId}`}>
+// zero.mutate.<namespace> dispatches by model namespace
+export const { useQuery, zero, run, preload, getQuery, zeroEvents } = clients.combined
+;<ProvideControlZero cacheURL={controlUrl} userID={user.id}>
+  <ProvideProjectZero cacheURL={projectUrl} userID={`${user.id}:${projectId}`}>
     <App />
-  </project.ProvideZero>
-</control.ProvideZero>
+  </ProvideProjectZero>
+</ProvideControlZero>
 ```
 
 constraints:
@@ -647,8 +577,7 @@ constraints:
 - each instance needs its own client-group identity (separate `userID` /
   storage key / cache url) — never swap the backing namespace under a live
   instance.
-- most apps should use plain `createZeroClient`; the `on-zero/multi` entrypoint
-  is only for this nested-provider edge case.
+- single-instance apps can keep using plain `createZeroClient`.
 - give the INNER slot to the instance owning the bulk of the subscriptions —
   inner queries use zero-react's native context path. outer instances use the
   direct adapter on their own mounted zero, so keep those instances on bounded,
@@ -656,35 +585,11 @@ constraints:
 - a mutator may only read/write tables owned by its own instance. its
   transaction runs on that instance alone; cross-instance writes are not
   detectable at registration and will silently miss the other store.
-- multiple clients do not mix server paths: keep using either the vanilla Zero
-  backend or the Orez backend selected above.
 - omitting `instanceName` keeps the exact single-instance behavior.
 
-**guarding the partition against drift.** a generated namespace that ends up in
-NEITHER instance's split silently un-registers its queries (a `useQuery` then
-throws "query not registered" at runtime, error-boundarying a whole screen). run
-`assertZeroInstancePartition` at module eval over each split so the drift is a
-boot throw instead — it also catches a namespace listed in more than one
-partition:
-
-```ts
-import { assertZeroInstancePartition } from 'on-zero/multi'
-
-assertZeroInstancePartition('query namespace', groupedQueries, {
-  control: controlQueries,
-  project: projectQueries,
-})
-assertZeroInstancePartition('model namespace', models, {
-  control: controlModels,
-  project: projectModels,
-})
-```
-
 ### server validation hooks
 
-the validation hooks belong to the engine-agnostic on-zero server bindings. add
-custom validation for all queries and mutations before attaching the bindings
-to your server executor:
+add custom validation for all queries and mutations:
 
 ```ts
 export const zeroBindings = createZeroServerBindings({
@@ -720,8 +625,7 @@ export const zeroBindings = createZeroServerBindings({
 ### mutation arg validation
 
 on-zero can auto-generate valibot validators for all mutation arguments. the
-validators belong to the server bindings rather than a particular executor.
-the generator uses the TypeScript type checker to deeply resolve param types -
+generator uses the TypeScript type checker to deeply resolve param types -
 including imported types, aliases, and cross-file references - then converts them
 to valibot schemas.
 
@@ -783,6 +687,11 @@ declare module 'on-zero' {
 }
 ```
 
+### Orez Lite (experimental)
+
+Orez Lite is our custom Rust engine and a separate alternative to vanilla Zero.
+it is still pre-alpha, so its setup is intentionally not documented here yet.
+
 ## mutation context
 
 every mutation receives `MutatorContext` as first argument:
@@ -796,6 +705,7 @@ type MutatorContext = {
   server?: {
     actions: ServerActions // async server functions
     enqueueTask(task: AsyncTask, opts?: { barrier?: boolean }): void
+    enqueueAction(action: AsyncAction, opts?: { barrier?: boolean }): void
   }
 }
 ```
@@ -827,6 +737,64 @@ response by default. Pass `{ barrier: true }` only when the client's next writes
 depend on the effect, such as provisioning a namespace before the client writes
 through a new Zero instance.
 
+### typed async actions
+
+for effects that may need to cross a worker or service-binding boundary, augment
+`Config.asyncAction` with a discriminated union and configure one executor on the
+server bindings:
+
+```ts
+type AppAction =
+  | { type: 'project.provisionNamespace'; projectId: string; userId: string }
+  | { type: 'project.invalidateAccess'; projectId: string }
+
+declare module 'on-zero' {
+  interface Config {
+    asyncAction: AppAction
+  }
+}
+
+const zeroBindings = createZeroServerBindings({
+  schema,
+  models,
+  createServerActions,
+  actions: {
+    execute: executeAppAction,
+    // when this runtime cannot execute app effects locally, inject a remote
+    // dispatcher. it becomes the only route; a failure never runs locally too.
+    dispatchRemote,
+  },
+})
+```
+
+mutators call `ctx.server?.enqueueAction(action, { barrier })`. on-zero schedules
+it through the same post-commit task mechanism as `enqueueTask`, preserving the
+barrier and auth scope without a global dispatcher.
+
+### awaiting and queueing mutations
+
+each `createZeroClient` result owns settlement helpers and one serial background
+queue:
+
+```ts
+await client.awaitMutationClient(client.zero.mutate.note.update(note), 'save note')
+await client.awaitMutationServer(client.zero.mutate.note.insert(note), 'create note')
+
+void client.enqueueBackgroundMutation(
+  'stream note',
+  () => client.zero.mutate.note.update(note),
+  { coalesceKey: `note:${note.id}` }
+)
+```
+
+the queue settles the client commit by default; use `settle: 'server'` only when
+later work requires the authoritative server row. same-key work that has not
+started is superseded by the newest write. recovery and instance replacement
+fence queued and in-flight work internally. direct settlement rejects with
+`StaleGenerationError`; the best-effort background queue drops that condition
+quietly. `MutationTimeoutError`, `MutationResultError`, and
+`mutationErrorMessage()` expose typed failure details.
+
 ## getAuth
 
 `getAuth()` returns the current user's auth data. works inside both queries and
@@ -854,33 +822,6 @@ import { ensureAuth } from 'on-zero'
 const auth = ensureAuth() // AuthData (throws if not authenticated)
 ```
 
-## custom client transport lifecycle
-
-vanilla Zero uses Zero's built-in WebSocket transport and does not pass a
-`transport` prop. Orez uses this extension point for its custom transport.
-
-pass the transport plugin to the provider so transport installation and Zero
-instance creation share one owner. on-zero only calls its `install(serverURL)`
-method:
-
-```tsx
-<client.ProvideZero
-  cacheURL={syncOrigin}
-  transport={transport}
->
-  {children}
-</client.ProvideZero>
-```
-
-The provider installs the plugin before constructing Zero, including after an
-instance rotation. The plugin owns its own idempotence and conflict behavior.
-
-Imperative consumers can call `client.waitForZero()` to await the provider's
-active instance without polling the throwing `client.zero` facade. Pass an
-`AbortSignal` when the wait belongs to a component effect.
-
-Transport-specific lifecycle events and logging belong to the selected plugin.
-
 ## recovery
 
 on-zero self-heals a client whose local sync state is lost or rejected. this is
@@ -905,9 +846,9 @@ drops the affected instance's local store and reloads the page ONCE. this covers
   `…LastMutationID`, `ClientNotFound`, `connection userID mismatch`. these
   surface only through the error log, so the log sink recovers on them too.
 
-genuinely app-infra signatures (your own synthesized ack-timeout marker, a
-cold-boot connect timeout) are NOT in this list — keep those app-side and use
-`benignLogFilter` to stop them from tripping recovery.
+two consecutive server acknowledgement timeouts also recover by default. one
+timeout remains a normal slow-server failure. configure the threshold with
+`serverAckTimeoutRecoveryThreshold` on `createZeroClient`.
 
 ### the hooks (all optional props on `ProvideZero`)
 
@@ -936,9 +877,10 @@ cold-boot connect timeout) are NOT in this list — keep those app-side and use
   (e.g. wait for the dev origin to come back so the reload doesn't hit a
   restarting server). composes with `scheduleReload`.
 
-- **`benignLogFilter?: (message) => boolean`** — return `true` for a classified
-  recovery log you want treated as benign so it does NOT recover (your app's
-  cold-boot timeout, say). only affects recovery; the log still reaches the sink.
+- **`benignLogPatterns?: readonly (string | RegExp)[]`**: classified recovery
+  logs matching one of these patterns remain benign. a client transport can
+  provide its own patterns through `transport.logClassifications.benign`; app and
+  transport patterns are combined. the log still reaches the sink.
 
 - **`refreshAuth?: () => Promise<string | undefined>`** — called when the
   connection enters `needs-auth` (an expired token). return a fresh token and
@@ -953,6 +895,11 @@ cold-boot connect timeout) are NOT in this list — keep those app-side and use
   `zeroReason`, `zeroCacheUrl`) for e2e/diagnostics. enable on ONE instance so
   multiple instances don't clobber the dataset.
 
+`zeroEvents` always carries a typed `reasonKey`. recovery events use
+`ZeroRecoveryReasonKey`; connection errors use `connection-error` or
+`connection-needs-auth`, so consumers can switch on stable keys instead of
+matching message strings.
+
 ### guard + latch semantics
 
 - a **per-reason guard** (60s window) means the SAME reason re-failing right
@@ -991,15 +938,11 @@ instead of surfacing a fatal error, deduped per reason. no configuration.
 
 **server-only mutations:**
 
-server-only mutations are available whenever the on-zero server bindings are
-attached to an executor. they are not specific to Orez:
-
 ```ts
 await zeroServer.mutate.user.insert(user)
 
 // with explicit auth (optional - authData auto-resolves from context)
 await zeroServer.mutate.user.insert(user, { authData: { id: userId, email } })
-
 ```
 
 the second argument is an options object:
@@ -1018,7 +961,7 @@ run a query once without subscribing. works on both client and server:
 
 ```ts
 import { run } from 'on-zero'
-import { userById } from '~/data/queries/user'
+import { userById } from '~/data/user/queries'
 
 // with params - defaults to cache only on client
 const user = await run(userById, { id: userId })
@@ -1045,7 +988,7 @@ use `getQuery` when you need the raw zero query object rather than subscribing v
 
 ```ts
 import { getQuery } from '~/zero/client'
-import { postById } from '~/data/queries/post'
+import { postById } from '~/data/post/queries'
 
 // returns the zero query object — same as what useQuery resolves internally
 const query = getQuery(postById, { postId: '123' })
@@ -1062,7 +1005,7 @@ preload query results into cache without subscribing:
 
 ```ts
 import { preload } from '~/zero/client'
-import { userNotifications } from '~/data/queries/notification'
+import { userNotifications } from '~/data/notification/queries'
 
 // preload after login
 const { complete, cleanup } = preload(userNotifications, { userId, limit: 100 })
@@ -1076,13 +1019,11 @@ useful for prefetching data before navigation to avoid loading states.
 
 **server-only queries:**
 
-like server-only mutations, these use the attached server executor and are not
-specific to Orez. for ad-hoc queries that don't use query functions:
+for ad-hoc queries that don't use query functions:
 
 ```ts
-const user = await zeroServer.query(
-  { userID: userId },
-  (q) => q.user.where('id', userId).one(),
+const user = await zeroServer.query({ userID: userId }, (q) =>
+  q.user.where('id', userId).one()
 )
 ```
 
@@ -1131,6 +1072,6 @@ await batchQuery(
       await processMessage(msg)
     }
   },
-  { chunk: 100, pause: 50 },
+  { chunk: 100, pause: 50 }
 )
 ```