on-zero 0.12.21 → 0.13.0

package/src/generate-layout.ts

@@ -8,6 +8,8 @@ export type DataNamespace = {
   instance: string
   queryPath: string | null
   modelPath: string | null
+  aggregatePath: string | null
+  table: string | null
   sourcePaths: string[]
 }
 
@@ -327,6 +329,59 @@ function namespaceExportKinds(
   return { model: false, query }
 }
 
+function mutationTable(
+  ts: typeof import('typescript'),
+  path: string,
+  namespace: string
+): string {
+  const source = ts.createSourceFile(
+    path,
+    readFileSync(path, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true
+  )
+  let schemaTable: string | null = null
+
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    if (
+      !statement.modifiers?.some(
+        (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword
+      )
+    ) {
+      continue
+    }
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue
+      if (
+        declaration.name.text === 'mutate' &&
+        ts.isCallExpression(declaration.initializer)
+      ) {
+        const firstArgument = declaration.initializer.arguments[0]
+        if (firstArgument && ts.isStringLiteralLike(firstArgument)) {
+          return firstArgument.text
+        }
+      }
+      if (declaration.name.text !== 'schema') continue
+      const visit = (node: ts.Node) => {
+        if (
+          ts.isCallExpression(node) &&
+          node.expression.getText(source) === 'table' &&
+          node.arguments[0] &&
+          ts.isStringLiteralLike(node.arguments[0])
+        ) {
+          schemaTable = node.arguments[0].text
+          return
+        }
+        ts.forEachChild(node, visit)
+      }
+      visit(declaration.initializer)
+    }
+  }
+
+  return schemaTable ?? namespace
+}
+
 function discoverNamespaces(
   ts: typeof import('typescript'),
   baseDir: string,
@@ -350,6 +405,8 @@ function discoverNamespaces(
         // a query-only file is not a model, matching the folder layout where a
         // missing mutations.ts leaves modelPath null
         modelPath: kinds.model ? path : null,
+        aggregatePath: null,
+        table: kinds.model ? mutationTable(ts, path, name) : null,
         sourcePaths: [path],
       })
       continue
@@ -360,9 +417,11 @@ function discoverNamespaces(
 
     const queryPath = resolve(folder, 'queries.ts')
     const modelPath = resolve(folder, 'mutations.ts')
+    const aggregatePath = resolve(folder, 'aggregates.ts')
     const hasQueries = existsSync(queryPath)
     const hasMutations = existsSync(modelPath)
-    if (!hasQueries && !hasMutations) {
+    const hasAggregates = existsSync(aggregatePath)
+    if (!hasQueries && !hasMutations && !hasAggregates) {
       if (
         ['models', 'mutations', 'queries'].includes(entry.name) &&
         readdirSync(folder).some(isSourceFile)
@@ -379,9 +438,13 @@ function discoverNamespaces(
       instance: instance.name,
       queryPath: hasQueries ? queryPath : null,
       modelPath: hasMutations ? modelPath : null,
-      sourcePaths: [hasQueries && queryPath, hasMutations && modelPath].filter(
-        (path): path is string => Boolean(path)
-      ),
+      aggregatePath: hasAggregates ? aggregatePath : null,
+      table: hasMutations ? mutationTable(ts, modelPath, entry.name) : null,
+      sourcePaths: [
+        hasQueries && queryPath,
+        hasMutations && modelPath,
+        hasAggregates && aggregatePath,
+      ].filter((path): path is string => Boolean(path)),
     })
   }
   return namespaces
@@ -803,11 +866,17 @@ export function discoverDataLayout(
     }
     namespaceOwners.set(namespace.name, namespace.instance)
   }
-  const tableOwners = new Map(
-    namespaces
-      .filter((namespace) => namespace.modelPath !== null)
-      .map((namespace) => [namespace.name, namespace.instance])
-  )
+  const tableOwners = new Map<string, string>()
+  for (const namespace of namespaces) {
+    if (namespace.table === null) continue
+    const owner = tableOwners.get(namespace.table)
+    if (owner && owner !== namespace.instance) {
+      throw new Error(
+        `[on-zero] table '${namespace.table}' is claimed by instances '${owner}' and '${namespace.instance}'`
+      )
+    }
+    tableOwners.set(namespace.table, namespace.instance)
+  }
 
   const metadata = metadataPaths(baseDir)
   const relations = relationTargets(ts, metadata)
@@ -816,8 +885,8 @@ export function discoverDataLayout(
   for (const instance of instances) {
     const tables = new Set(
       instance.namespaces
-        .filter((namespace) => namespace.modelPath !== null)
-        .map((namespace) => namespace.name)
+        .map((namespace) => namespace.table)
+        .filter((table): table is string => table !== null)
     )
     const syncTables = new Set(tables)
     for (const namespace of instance.namespaces) {

package/src/generate-lite.test.ts

@@ -118,6 +118,46 @@ describe('generateLite', () => {
     expect(result.instances[0]?.syncTables).toEqual([])
   })
 
+  test('compiles every namespace aggregates.ts into one generated set', () => {
+    const files = {
+      [`${DIR}/post/queries.ts`]: '// queries',
+      [`${DIR}/post/aggregates.ts`]: '// declarations only',
+      [`${DIR}/order/aggregates.ts`]: '// declarations only',
+    }
+    const result = generateLite({
+      files,
+      dir: DIR,
+      parse: makeParse({
+        [`${DIR}/post/queries.ts`]: { mutations: [], queries: [] },
+      }),
+    })
+
+    const generated = result.files['aggregates.ts']
+    expect(generated).toBeDefined()
+    // a folder holding only aggregates.ts is still a namespace, and the
+    // aggregate module is never parsed — it is imported, not read.
+    expect(generated).toContain(
+      `import { aggregates as orderAggregates } from '../order/aggregates'`
+    )
+    expect(generated).toContain(
+      `import { aggregates as postAggregates } from '../post/aggregates'`
+    )
+    expect(generated).toContain(
+      'mergeAggregateDefinitions(orderAggregates, postAggregates)'
+    )
+  })
+
+  test('omits the generated aggregate set when no namespace declares one', () => {
+    const files = { [`${DIR}/post/queries.ts`]: '// queries' }
+    const result = generateLite({
+      files,
+      dir: DIR,
+      parse: makeParse({ [`${DIR}/post/queries.ts`]: { mutations: [], queries: [] } }),
+    })
+
+    expect(result.files['aggregates.ts']).toBeUndefined()
+  })
+
   test('derives fileless support tables through parsed mutation helpers', () => {
     const files = {
       [`${DIR}/post.ts`]: '// namespace',
@@ -166,6 +206,22 @@ describe('generateLite', () => {
     expect(context.instances?.default?.supportTables).toEqual(['audit', 'settings'])
   })
 
+  test('derives mutation membership from the targeted table', () => {
+    const path = `${DIR}/mint/mutations.ts`
+    const result = generateLite({
+      files: { [path]: '// namespace' },
+      dir: DIR,
+      parse: makeParse({
+        [path]: {
+          mutations: [{ modelName: 'expense', handlers: [], schema: null }],
+          queries: [],
+        },
+      }),
+    })
+
+    expect(result.instances[0]?.syncTables).toEqual(['expense'])
+  })
+
   test('includes a fileless support table in every lite instance that uses it', () => {
     const files = {
       [`${DIR}/on-zero.config.ts`]: `export default defineConfig({ instances: { control: { dir: './planes/control', supportTables: ['manual'] }, project: { scope: 'projectId' } } })`,

package/src/generate-lite.ts

@@ -15,6 +15,7 @@
 // contexts without pulling in ~10mb of typescript.
 
 import {
+  generateAggregatesFile,
   generateGroupedQueriesFile,
   generateInstancesFile,
   generateModelsFile,
@@ -34,9 +35,8 @@ import type { ModelMutations, SchemaColumn } from './generate-helpers'
 // minimal ast info about a namespace mutation module (e.g. `post/mutations.ts`)
 export type LiteMutationExport = {
   // the first arg to `mutations('NAME', ...)` — string literal from the source.
-  // not currently emitted anywhere in the output; the model file basename is
-  // used for the top-level key in syncedMutations instead. kept for parity with
-  // what callers naturally extract, and to leave room for future use.
+  // this targets membership at the named table while the model file basename
+  // remains the top-level key in syncedMutations.
   modelName: string
   // handlers = keys of the last object literal arg to `mutations(...)`
   handlers: Array<{
@@ -218,6 +218,7 @@ type LiteNamespace = {
   instance: string
   queryPath: string | null
   modelPath: string | null
+  aggregatePath: string | null
 }
 
 type LiteInstance = {
@@ -381,6 +382,7 @@ function discoverLiteLayout(
         instance: instance.name,
         queryPath: path,
         modelPath: path,
+        aggregatePath: null,
       })
     }
 
@@ -396,7 +398,8 @@ function discoverLiteLayout(
       if (folder === `${baseDir}/generated` || instanceDirs.has(folder)) continue
       const queries = `${folder}/queries.ts`
       const mutations = `${folder}/mutations.ts`
-      if (!(queries in files) && !(mutations in files)) {
+      const aggregates = `${folder}/aggregates.ts`
+      if (!(queries in files) && !(mutations in files) && !(aggregates in files)) {
         const oldName = baseName(folder)
         if (
           ['models', 'mutations', 'queries'].includes(oldName) &&
@@ -414,6 +417,7 @@ function discoverLiteLayout(
         instance: instance.name,
         queryPath: queries in files ? queries : null,
         modelPath: mutations in files ? mutations : null,
+        aggregatePath: aggregates in files ? aggregates : null,
       })
     }
   }
@@ -464,6 +468,7 @@ export function generateLite(opts: LiteGenerateOptions): LiteGenerateResult {
   // parse each model file and build ModelMutations records for the emitter
   const allModelMutations: ModelMutations[] = []
   const modelNamesWithSchema: string[] = []
+  const modelTables = new Map<string, string>()
 
   for (const namespace of modelNamespaces) {
     const filePath = namespace.modelPath
@@ -473,6 +478,10 @@ export function generateLite(opts: LiteGenerateOptions): LiteGenerateResult {
 
     // a model file has at most one mutate export, but the lite ast is an array
     const mutationExport = parsed.mutations[0] ?? null
+    modelTables.set(
+      modelName,
+      mutationExport?.modelName || mutationExport?.schema?.tableName || modelName
+    )
 
     // extract schema info if present
     const columns: Record<string, SchemaColumn> = {}
@@ -612,9 +621,17 @@ export function generateLite(opts: LiteGenerateOptions): LiteGenerateResult {
     }
   }
 
-  const owners = new Map(
-    modelNamespaces.map((namespace) => [namespace.name, namespace.instance])
-  )
+  const owners = new Map<string, string>()
+  for (const namespace of modelNamespaces) {
+    const table = modelTables.get(namespace.name)!
+    const owner = owners.get(table)
+    if (owner && owner !== namespace.instance) {
+      throw new Error(
+        `[on-zero] table '${table}' is claimed by instances '${owner}' and '${namespace.instance}'`
+      )
+    }
+    owners.set(table, namespace.instance)
+  }
   const relatedOwners = new Map<string, string>()
   const directTables = new Map<string, string[]>()
   const syncTables = new Map<string, string[]>()
@@ -622,7 +639,7 @@ export function generateLite(opts: LiteGenerateOptions): LiteGenerateResult {
     const direct = new Set(
       instance.namespaces
         .filter((namespace) => namespace.modelPath !== null)
-        .map((namespace) => namespace.name)
+        .map((namespace) => modelTables.get(namespace.name)!)
     )
     const synced = new Set(direct)
     for (const namespace of instance.namespaces) {
@@ -730,7 +747,6 @@ export function generateLite(opts: LiteGenerateOptions): LiteGenerateResult {
       importPath: `../${relativePath(baseDir, namespace.modelPath).replace(/\.ts$/, '')}`,
     }))
   )
-
   if (modelNamesWithSchema.length > 0) {
     out['types.ts'] = generateTypesFile(modelNamesWithSchema)
     out['tables.ts'] = generateTablesFile(
@@ -767,6 +783,19 @@ export function generateLite(opts: LiteGenerateOptions): LiteGenerateResult {
     out['syncedMutations.ts'] = generateSyncedMutationsFile(allModelMutations)
   }
 
+  const aggregateNamespaces = namespaces.filter(
+    (namespace): namespace is LiteNamespace & { aggregatePath: string } =>
+      namespace.aggregatePath !== null
+  )
+  if (aggregateNamespaces.length > 0) {
+    out['aggregates.ts'] = generateAggregatesFile(
+      aggregateNamespaces.map((namespace) => ({
+        name: namespace.name,
+        importPath: `../${relativePath(baseDir, namespace.aggregatePath).replace(/\.ts$/, '')}`,
+      }))
+    )
+  }
+
   // count mutations the same way `generate()` does: 3 per crud model plus
   // non-crud custom mutations (the crud-ops set is excluded when hasCRUD).
   let mutationCount = 0

package/src/generate.test.ts

@@ -200,6 +200,25 @@ export async function writeAudit(tx: Transaction) {
     })
   })
 
+  test('derives mutation membership from the targeted table', async () => {
+    writeFileSync(
+      join(dataDir(), 'mint/mutations.ts'),
+      `export const mutate = mutations('expense', permissions, { save: async () => {} })`
+    )
+
+    await expect(deriveDataMembership({ dir: dataDir() })).resolves.toEqual({
+      instances: {
+        default: {
+          tables: ['expense'],
+          syncTables: ['expense'],
+          supportTables: [],
+          scope: null,
+        },
+      },
+      allTables: ['expense'],
+    })
+  })
+
   test('includes a fileless support table in every instance that uses it', async () => {
     writeFileSync(
       join(dataDir(), 'control/account.ts'),

package/src/generate.ts

@@ -4,6 +4,7 @@ import { basename, dirname, resolve } from 'node:path'
 
 import {
   formatObjectKey,
+  generateAggregatesFile,
   generateGroupedQueriesFile,
   generateInstancesFile,
   generateModelsFile,
@@ -22,7 +23,7 @@ import type { ExtractedMutation, ModelMutations, SchemaColumn } from './generate
 import type { DataLayout } from './generate-layout'
 
 const hash = (s: string) => createHash('sha256').update(s).digest('hex')
-const GENERATOR_CACHE_VERSION = '5'
+const GENERATOR_CACHE_VERSION = '6'
 
 const isGeneratorSourceFile = (name: string) =>
   name.endsWith('.ts') &&
@@ -1028,7 +1029,6 @@ export async function generate(options: GenerateOptions): Promise<GenerateResult
     name: namespace.name,
     importPath: namespaceImportPath(baseDir, namespace.modelPath),
   }))
-
   const writeResults = [
     writeFileIfChanged(
       resolve(generatedDir, 'models.ts'),
@@ -1196,6 +1196,23 @@ export async function generate(options: GenerateOptions): Promise<GenerateResult
   )
   if (instancesChanged) filesChanged++
 
+  const aggregateNamespaces = layout.namespaces.filter(
+    (namespace): namespace is typeof namespace & { aggregatePath: string } =>
+      namespace.aggregatePath !== null
+  )
+  if (aggregateNamespaces.length > 0) {
+    const aggregatesChanged = writeFileIfChanged(
+      resolve(generatedDir, 'aggregates.ts'),
+      generateAggregatesFile(
+        aggregateNamespaces.map((namespace) => ({
+          name: namespace.name,
+          importPath: namespaceImportPath(baseDir, namespace.aggregatePath),
+        }))
+      )
+    )
+    if (aggregatesChanged) filesChanged++
+  }
+
   // generate mutation validators from model files
   const allModelMutations: ModelMutations[] = []
 

package/src/helpers/createMutators.test.ts

@@ -1,5 +1,5 @@
 import { createBuilder, createSchema, number, string, table } from '@rocicorp/zero'
-import { count, defineRollups } from 'orez-lite/rollup'
+import { count, defineAggregates } from 'orez-lite/aggregate'
 import { afterEach, describe, expect, test, vi } from 'vitest'
 
 import { setSchema } from '../state'
@@ -53,7 +53,7 @@ describe('createMutators timeout guard', () => {
   })
 })
 
-test('createMutators installs optimistic rollups on client transactions', async () => {
+test('createMutators installs optimistic aggregates on client transactions', async () => {
   const comment = table('comment')
     .columns({ id: string(), postId: string() })
     .primaryKey('id')
@@ -62,13 +62,13 @@ test('createMutators installs optimistic rollups on client transactions', async
     .primaryKey('id')
   const schema = createSchema({ tables: [comment, post] })
   setSchema(schema, createBuilder(schema))
-  const rollups = defineRollups(schema, {
+  const aggregates = defineAggregates(schema, {
     postCommentCount: {
       source: 'comment',
       target: 'post',
       mode: 'existing',
       groupBy: { postId: 'id' },
-      aggregates: { commentCount: count() },
+      columns: { commentCount: count() },
     },
   })
   const rows: Record<string, Array<Record<string, unknown>>> = {
@@ -122,7 +122,7 @@ test('createMutators installs optimistic rollups on client transactions', async
     environment: 'client',
     authData: null,
     bindCan: () => async () => {},
-    rollups,
+    aggregates,
     models: {
       comment: {
         mutate: {

package/src/helpers/createMutators.ts

@@ -1,4 +1,4 @@
-import { withOptimisticRollups } from 'orez-lite/rollup'
+import { withOptimisticAggregates } from 'orez-lite/aggregate'
 
 import { getAuthData } from '../state'
 import { mapObject } from './mapObject'
@@ -13,7 +13,7 @@ import type {
   MutatorContext,
   Transaction,
 } from '../types'
-import type { RollupSet } from 'orez-lite/rollup'
+import type { AggregateSet } from 'orez-lite/aggregate'
 
 export type ValidateMutationFn = (args: {
   authData: AuthData | null
@@ -35,7 +35,7 @@ export function createMutators<Models extends GenericModels>({
   validateMutation,
   mutationValidators,
   resolveAuthData,
-  rollups,
+  aggregates,
 }: {
   environment: 'server' | 'client'
   authData: AuthData | null
@@ -48,7 +48,7 @@ export function createMutators<Models extends GenericModels>({
   /** valibot schemas keyed by model.mutationName, auto-validates args before running */
   mutationValidators?: Record<string, Record<string, any>>
   resolveAuthData?: () => AuthData | null
-  rollups?: RollupSet
+  aggregates?: AggregateSet
 }): GetZeroMutators<Models> {
   const serverActions = createServerActions?.()
 
@@ -60,7 +60,9 @@ export function createMutators<Models extends GenericModels>({
   function withContext<Args extends any[]>(fn: (...args: Args) => Promise<void>) {
     return async (tx: Transaction, ...args: Args): Promise<void> => {
       const transaction =
-        environment === 'client' && rollups ? withOptimisticRollups(tx, rollups) : tx
+        environment === 'client' && aggregates
+          ? withOptimisticAggregates(tx, aggregates)
+          : tx
       // on client, read authData dynamically to avoid stale closure during auth
       // transitions (ZeroProvider recreates Zero instance in useEffect, but
       // mutations can run before that)

package/src/helpers/recoverZeroClient.test.ts

@@ -90,6 +90,34 @@ describe('zero recovery', () => {
     expect(a.reload.mock.calls.length + b.reload.mock.calls.length).toBe(1)
   })
 
+  test('combined native client remints every instance when page reload is unavailable', async () => {
+    const a = setup()
+    const b = setup()
+    a.deps.reload = undefined
+    b.deps.reload = undefined
+    const recoverA = vi.fn(() => Promise.resolve(true))
+    const recoverB = vi.fn(() => Promise.resolve(true))
+    a.deps.recoverInPlace = recoverA
+    b.deps.recoverInPlace = recoverB
+    const originalLocation = globalThis.location
+    Object.defineProperty(globalThis, 'location', {
+      configurable: true,
+      value: undefined,
+    })
+    try {
+      makeZeroRecovery(a.deps).onClientStateNotFound()
+      makeZeroRecovery(b.deps).onClientStateNotFound()
+      await flush()
+    } finally {
+      Object.defineProperty(globalThis, 'location', {
+        configurable: true,
+        value: originalLocation,
+      })
+    }
+    expect(recoverA).toHaveBeenCalledTimes(1)
+    expect(recoverB).toHaveBeenCalledTimes(1)
+  })
+
   test('a second trigger in the same page-load adds no extra reload or fatal', async () => {
     const { deps, reload, events } = setup()
     const recovery = makeZeroRecovery(deps)
@@ -240,10 +268,9 @@ describe('zero recovery', () => {
 
   // a host with a `window` shim but no real `location` — the sootsim tenant
   // render-worker, which hides `location` for isolation. the DEFAULT reload
-  // path (no injected `deps.reload`) must still drop stale IDB and not throw
-  // "reading 'reload'" on undefined; it no-ops the reload and lets the host
-  // remount. previously crashed as an unhandled rejection.
-  test('default reload path is a safe no-op when location is absent', async () => {
+  // path (no injected `deps.reload`) must still drop stale IDB and reconstruct
+  // the client in place rather than leaving the worker on the rejected client.
+  test('default reload path remints in place when location is absent', async () => {
     const events: ZeroEvent[] = []
     const zeroEvents = createEmitter<ZeroEvent | null>(
       `test-recover-${emitterSeq++}`,
@@ -253,8 +280,9 @@ describe('zero recovery', () => {
       if (event) events.push(event)
     })
     const deleteLocalState = vi.fn(() => Promise.resolve())
+    const recoverInPlace = vi.fn(() => Promise.resolve(true))
     // no `reload` dep — exercises the default `globalThis.location?.reload?.()`.
-    const deps: ZeroRecoveryDeps = { deleteLocalState, zeroEvents }
+    const deps: ZeroRecoveryDeps = { deleteLocalState, zeroEvents, recoverInPlace }
     const originalLocation = globalThis.location
     // simulate the worker: window exists (jsdom) but location is absent.
     Object.defineProperty(globalThis, 'location', {
@@ -271,6 +299,7 @@ describe('zero recovery', () => {
       })
     }
     expect(deleteLocalState).toHaveBeenCalledTimes(1)
+    expect(recoverInPlace).toHaveBeenCalledTimes(1)
     expect(events).toContainEqual({
       type: 'recovering',
       reasonKey: 'client-state-not-found',

package/src/helpers/recoverZeroClient.ts

@@ -80,8 +80,11 @@ export type ZeroRecoveryDeps = {
   // internal lifecycle fence. recovery invalidates queued and in-flight work
   // before the consumer can defer the reload.
   onRecovery?: (reasonKey: ZeroRecoveryReasonKey) => void
+  // non-DOM hosts cannot reload a page. reconstruct the mounted client in
+  // place after the same delete/beforeReload work completes.
+  recoverInPlace?: () => Promise<boolean>
   // injectable for tests; defaults to a real page reload.
-  reload?: () => void
+  reload?: () => void | boolean
 }
 
 // one reload per page-load. the local-state deletes that must precede it are
@@ -94,6 +97,7 @@ let reloadScheduled = false
 let reloadInProgress = false
 let reloadLatchTimer: ReturnType<typeof setTimeout> | undefined
 const pendingDeletes: Array<() => Promise<unknown>> = []
+const pendingInPlaceRecoveries: Array<() => Promise<boolean>> = []
 
 // within-a-page-load per-reason guard: real loop protection everywhere,
 // including Hermes (no storage needed). a reload wipes it, which is why the
@@ -192,15 +196,39 @@ function performReload(deps: ZeroRecoveryDeps): Promise<void> {
   // (`getBrowserGlobal('location')?.reload()`, zero.js): read location off the
   // global and optional-chain through it. a non-DOM host with a `window` shim
   // but no real `location` (the sootsim tenant render-worker hides `location`
-  // for isolation) then drops its stale IDB and no-ops the reload — letting the
-  // host remount — instead of throwing "reading 'reload'" on undefined.
-  const doReload = deps.reload ?? (() => globalThis.location?.reload?.())
+  // for isolation) reconstructs the client in place after the same cleanup.
+  const doReload =
+    deps.reload ??
+    (() => {
+      const reload = globalThis.location?.reload
+      if (!reload) return false
+      reload.call(globalThis.location)
+      return true
+    })
+  let inPlaceRecoveries: Array<() => Promise<boolean>> = []
   return Promise.resolve()
-    .then(() => Promise.allSettled(pendingDeletes.splice(0).map((run) => run())))
+    .then(() => {
+      inPlaceRecoveries = pendingInPlaceRecoveries.splice(0)
+      return Promise.allSettled(pendingDeletes.splice(0).map((run) => run()))
+    })
     .then(() => deps.beforeReload?.())
     .catch(() => {})
-    .then(() => {
-      doReload()
+    .then(async () => {
+      const reloadStarted = doReload()
+      if (reloadStarted !== false) return
+      try {
+        const results = await Promise.all(inPlaceRecoveries.map((recover) => recover()))
+        if (inPlaceRecoveries.length > 0 && results.some((recovered) => !recovered)) {
+          console.error('[on-zero] recovery could not reload or reconstruct the client')
+        }
+      } catch (error) {
+        console.error('[on-zero] in-place recovery failed', error)
+      } finally {
+        // a page reload tears down this module, but an in-place recovery keeps
+        // it alive. reopen the latch so a later, distinct failure can recover.
+        reloadInProgress = false
+        reloadScheduled = false
+      }
     })
 }
 
@@ -218,6 +246,7 @@ function recover(
   if (dropLocalState) {
     pendingDeletes.push(() => Promise.resolve().then(deps.deleteLocalState))
   }
+  if (deps.recoverInPlace) pendingInPlaceRecoveries.push(deps.recoverInPlace)
   // only ONE reload per page-load; a later trigger just contributes its delete.
   if (reloadScheduled) return
   if (!recoveryGuardOpen(reasonKey, deps.guardStorage)) {
@@ -461,7 +490,7 @@ export function isRecoverableZeroStalePokeMessage(message: string): boolean {
   )
 }
 
-// test-only: the reload latch + pending deletes + in-memory guard are in-memory
+// test-only: the reload latch + pending work + in-memory guard are in-memory
 // (a real page reload clears them); tests simulate that reset between successive
 // "page loads". the injectable/sessionStorage guard is NOT cleared here — like a
 // real reload, it survives, which is what catches an immediate re-fire.
@@ -473,6 +502,7 @@ export function resetRecoveryStateForTests() {
     reloadLatchTimer = undefined
   }
   pendingDeletes.length = 0
+  pendingInPlaceRecoveries.length = 0
   lastStoreClosedAtMs = 0
   inMemoryGuard.clear()
 }

package/src/helpers/useMutation.test.ts

@@ -95,6 +95,21 @@ describe('observeMutation', () => {
     await expect(observeMutation(result)).resolves.toBeUndefined()
   })
 
+  test('observing the same result twice emits globally once', async () => {
+    const { result, client, server } = fakeResult()
+    const global: MutationError[] = []
+    const dispose = onMutationError((e) => global.push(e))
+
+    const first = observeMutation(result)
+    const second = observeMutation(result)
+    client.resolve(SUCCESS)
+    server.resolve(appError('denied'))
+    await Promise.all([first, second])
+
+    expect(global).toHaveLength(1)
+    dispose()
+  })
+
   test('with no listener registered it falls back to console.error in dev', async () => {
     const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
     const { result, client, server } = fakeResult()