orez-sync-cf-host 0.5.17 → 0.5.19

package/src/host.ts

@@ -1,12 +1,23 @@
 import { DurableObject } from 'cloudflare:workers'
 
 import { validatePullCaps, validateSyncHostConfig } from './config.js'
+import { createPostCommitEffects } from './post-commit.js'
+import { createQueryCompiler } from './query-compiler.js'
 import {
+  decodeSqlParams,
+  SqlStorageDirect,
+  SqlStorageMutatorTransaction,
+  SqlStorageSyncDb,
+} from './sql-storage-adapter.js'
+import { isMutationApplicationError } from './types.js'
+import {
+  engine_apply_snapshot_changes,
+  engine_apply_snapshot_page,
   engine_apply_upstream,
-  engine_apply_upstream_snapshot,
   engine_assemble_push_response,
-  engine_compile_query,
+  engine_begin_snapshot_generation,
   engine_finalize,
+  engine_finalize_snapshot_generation,
   engine_handle_pull,
   engine_handle_query_pull,
   engine_init_query_schema,
@@ -16,18 +27,11 @@ import {
   engine_preflight,
   engine_prune,
   engine_push_validate,
+  engine_read_snapshot_progress,
   engine_record_app_error,
   engine_state,
   engine_version,
-  initSync,
-} from './generated/sync_wasm.js'
-import wasmModule from './generated/sync_wasm_bg.wasm'
-import {
-  SqlStorageDirect,
-  SqlStorageMutatorTransaction,
-  SqlStorageSyncDb,
-} from './sql-storage-adapter.js'
-import { MutationApplicationError } from './types.js'
+} from './wasm.js'
 import {
   IngestBreakerError,
   IngestCircuitBreaker,
@@ -36,7 +40,6 @@ import {
 } from './write-safeguards.js'
 
 import type {
-  DeferredEffect,
   JsonValue,
   NormalizedClaims,
   PullCaps,
@@ -44,11 +47,11 @@ import type {
   SyncHostEnv,
 } from './types.js'
 
-initSync({ module: wasmModule })
-
 const CLAIMS_HEADER = 'x-orez-sync-claims'
 const NAMESPACE_HEADER = 'x-orez-sync-namespace'
 const UPSTREAM_PATH_HEADER = 'x-orez-sync-upstream-path'
+const DEFAULT_SNAPSHOT_PAGE_ROWS = 2_000
+const MIN_SNAPSHOT_PAGE_ROWS = 100
 const DEFAULT_CAPS: PullCaps = {
   maxChangeRows: 10_000,
   maxChangeBytes: 2_000_000,
@@ -96,6 +99,19 @@ type ApplyUpstreamResult = {
   applied: number
   caughtUp: boolean
 }
+type SnapshotProgress = {
+  generation: string
+  startWatermark: string
+  table: string | null
+  cursor: string | null
+  state: 'paging' | 'catching_up'
+  catchupWatermark: string
+}
+type SnapshotPage = {
+  watermark: number
+  rows: Record<string, unknown>[]
+  nextCursor: string | null
+}
 type SocketAttachment = { clientID: string }
 type FaultPoint =
   | 'push_before_mutation'
@@ -253,7 +269,15 @@ export function createSyncWorker<Env extends SyncHostEnv>(
 
       const route = routeAfterNamespace(new URL(request.url).pathname)
       const isAdmin = route.startsWith('/admin/')
-      if (isAdmin) {
+      if (route === '/wake') {
+        if (!(await config.authorizeWake(request, env))) {
+          return json({ error: 'missing wake capability' }, 401)
+        }
+      } else if (route === '/notify') {
+        if (!(await config.authorizeNotify(request, env))) {
+          return json({ error: 'forbidden' }, 403)
+        }
+      } else if (isAdmin) {
         const authorized = config.authorizeAdmin
           ? await config.authorizeAdmin(request, env)
           : Boolean(env.ADMIN_KEY) && request.headers.get('x-admin-key') === env.ADMIN_KEY
@@ -264,10 +288,6 @@ export function createSyncWorker<Env extends SyncHostEnv>(
       headers.delete(CLAIMS_HEADER)
       headers.delete(NAMESPACE_HEADER)
       headers.delete(UPSTREAM_PATH_HEADER)
-      // Wake sockets carry only a client ID and the literal "wake" hint; they
-      // expose no rows, claims, or mutation state. Keep this advisory channel
-      // compatible with the vendored transport, which cannot attach an HTTP
-      // Authorization header to its native WebSocket constructor.
       if (!isAdmin && route !== '/wake' && route !== '/notify') {
         const claims = await config.authenticate(request, env)
         if (!claims) return json({ error: 'missing authentication' }, 401)
@@ -297,6 +317,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
   config: SyncHostConfig<Env>
 ) {
   validateSyncHostConfig(config)
+  const compileQuery = createQueryCompiler(config.schema)
   const defaultRetainChanges = String(config.retainChanges ?? 4_096)
   const caps: PullCaps = validatePullCaps({ ...DEFAULT_CAPS, ...config.caps })
   const idleTeardownMs = config.idleTeardownMs ?? 5_000
@@ -328,6 +349,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
     #wakeRecipients = new Set<WebSocket>()
     #wakePromise: Promise<void> | null = null
     #ingestPromise: Promise<number> | null = null
+    #queryPullLocks = new Map<string, Promise<void>>()
     #recordingIngestBillable = false
     #ingestBreaker = new IngestCircuitBreaker({
       budgetRows: ingestBudgetRows,
@@ -344,8 +366,10 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
       }
       this.#engineDb = new SqlStorageSyncDb(ctx.storage.sql, recordRowsWritten)
       this.#directSql = new SqlStorageDirect(ctx.storage.sql, recordRowsWritten)
-      this.#mutatorSql = new SqlStorageMutatorTransaction(this.#directSql, (ast) =>
-        this.#wasm(() => engine_compile_query(config.schema, ast))
+      this.#mutatorSql = new SqlStorageMutatorTransaction(
+        this.#directSql,
+        (ast, format) => this.#wasm(() => compileQuery(ast, format)),
+        config.transactionQueryBudget
       )
       ctx.blockConcurrencyWhile(async () => {
         ctx.storage.transactionSync(() => {
@@ -391,6 +415,22 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
       return call()
     }
 
+    async #acquireQueryPullLock(clientGroupID: string): Promise<() => void> {
+      const previous = this.#queryPullLocks.get(clientGroupID)
+      let release!: () => void
+      const current = new Promise<void>((resolve) => {
+        release = resolve
+      })
+      this.#queryPullLocks.set(clientGroupID, current)
+      if (previous) await previous
+      return () => {
+        release()
+        if (this.#queryPullLocks.get(clientGroupID) === current) {
+          this.#queryPullLocks.delete(clientGroupID)
+        }
+      }
+    }
+
     #simulateIdleTeardown(now: number): void {
       if (this.#lastRequestAt > 0 && now - this.#lastRequestAt >= idleTeardownMs) {
         this.#bootID = crypto.randomUUID()
@@ -505,9 +545,13 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
       )
     }
 
-    #engineState(): EngineState | null {
+    #engineState(): EngineState {
+      return this.#wasm(() => engine_state(this.#engineDb)) as EngineState
+    }
+
+    #engineStateBestEffort(): EngineState | null {
       try {
-        return this.#wasm(() => engine_state(this.#engineDb)) as EngineState
+        return this.#engineState()
       } catch {
         return null
       }
@@ -533,7 +577,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
     async #upstreamWriteBudgetStatus(): Promise<Response> {
       if (!config.upstream) return json({ error: 'upstream is not configured' }, 404)
       const path = this.#controlGet('upstreamPath')
-      if (!path) return json({ error: 'upstream path is not known yet' }, 409)
+      if (path === null) return json({ error: 'upstream path is not known yet' }, 409)
       const endpoint = new URL(`${path}/_orez/write-budget`, 'https://upstream.invalid')
       const response = await this.#serviceBinding().fetch(endpoint.toString(), {
         headers: { host: endpoint.host },
@@ -553,7 +597,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
     #rememberUpstreamPath(request: Request): string | null {
       if (!config.upstream) return null
       const path = request.headers.get(UPSTREAM_PATH_HEADER)
-      if (path) {
+      if (path !== null) {
         this.#controlSet('upstreamPath', path)
         return path
       }
@@ -591,9 +635,14 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
         return apply()
       } catch (error) {
         this.#recordingIngestBillable = false
-        if (error instanceof IngestBreakerError) {
+        const status = this.#ingestBreaker.status()
+        // a breaker thrown by the sql adapter crosses rust as an engine error,
+        // so the durable breaker state is the authoritative classification.
+        if (
+          error instanceof IngestBreakerError ||
+          (status.tripped && status.reason === 'ingestBudgetExceeded')
+        ) {
           this.#persistIngestBreaker()
-          const status = this.#ingestBreaker.status()
           console.error(
             JSON.stringify({
               event: 'sync_upstream_ingest_breaker_tripped',
@@ -609,37 +658,124 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
       }
     }
 
-    async #applyUpstreamSnapshot(
+    #snapshotProgress(): SnapshotProgress | null {
+      return this.#wasm(() =>
+        engine_read_snapshot_progress(this.#engineDb)
+      ) as SnapshotProgress | null
+    }
+
+    #resetSnapshotBillingWindow(): void {
+      // every page is an independently committed write unit. metering it in a
+      // fresh window keeps a rebuild larger than the breaker ceiling resumable
+      // while preserving the ceiling for each transaction.
+      this.#ingestBreaker.reopen()
+      this.#controlDelete(
+        'ingestBreakerReason',
+        'ingestBreakerRetryAt',
+        'ingestBreakerTrips'
+      )
+    }
+
+    #snapshotRetryLimit(
+      error: unknown,
+      limit: number,
+      fields: Record<string, unknown>
+    ): number {
+      const status = statusOf(error)
+      if (!(error instanceof IngestBreakerError) && status < 500) throw error
+      if (limit <= MIN_SNAPSHOT_PAGE_ROWS) {
+        throw Object.assign(
+          new Error(
+            `snapshot page failed at minimum limit ${MIN_SNAPSHOT_PAGE_ROWS}: ${errorMessage(error)}`
+          ),
+          { status, cause: error }
+        )
+      }
+      const nextLimit = Math.max(MIN_SNAPSHOT_PAGE_ROWS, Math.floor(limit / 2))
+      console.warn(
+        JSON.stringify({
+          event: 'sync_upstream_snapshot_page_retry',
+          ...fields,
+          limit,
+          nextLimit,
+          status,
+          error: errorMessage(error),
+        })
+      )
+      return nextLimit
+    }
+
+    async #fetchSnapshotPage(
       path: string,
-      cursor: string,
-      allowSameCursor: boolean
-    ): Promise<ApplyUpstreamResult> {
+      table: string,
+      cursor: string | null,
+      limit: number
+    ): Promise<SnapshotPage> {
       const endpoint = new URL(`${path}/snapshot`, 'https://upstream.invalid')
+      endpoint.searchParams.set('table', table)
+      endpoint.searchParams.set('limit', String(limit))
+      if (cursor !== null) endpoint.searchParams.set('cursor', cursor)
       const response = await this.#serviceBinding().fetch(endpoint.toString(), {
         headers: { host: endpoint.host },
       })
       if (!response.ok) {
-        throw new Error(`upstream snapshot returned ${response.status}`)
-      }
-      const snapshot = await response.json()
-      const rebuilt = this.#withIngestBilling({ phase: 'snapshot', cursor }, () =>
-        this.ctx.storage.transactionSync(() =>
-          this.#wasm(() =>
-            engine_apply_upstream_snapshot(this.#engineDb, config.schema, snapshot)
-          )
+        throw requestError(
+          `upstream snapshot page returned ${response.status}`,
+          response.status >= 500 ? 502 : response.status
         )
-      ) as ApplyUpstreamResult
-      this.#recordIngestLogicalRows(rebuilt.applied)
-      const nextCursor = this.#engineState()?.upstreamWatermark ?? cursor
-      if (!allowSameCursor && String(nextCursor) === String(cursor)) {
-        this.#tripIngest('ingestCursorStalled', {
-          phase: 'snapshot',
-          cursor,
-          resultWatermark: rebuilt.watermark,
-          applied: rebuilt.applied,
-        })
       }
-      return rebuilt
+      const page = (await response.json()) as Partial<SnapshotPage>
+      if (
+        !Number.isSafeInteger(page.watermark) ||
+        Number(page.watermark) < 0 ||
+        !Array.isArray(page.rows) ||
+        (page.nextCursor !== null && typeof page.nextCursor !== 'string')
+      ) {
+        throw new Error('invalid upstream snapshot page response')
+      }
+      return page as SnapshotPage
+    }
+
+    async #beginSnapshotGeneration(path: string): Promise<{
+      progress: SnapshotProgress
+      page: SnapshotPage
+      pageLimit: number
+    }> {
+      const table = Object.keys(config.schema.tables).sort()[0]
+      if (!table) throw requestError('paged snapshots require a modeled table', 500)
+      let pageLimit = DEFAULT_SNAPSHOT_PAGE_ROWS
+      let page: SnapshotPage
+      for (;;) {
+        try {
+          page = await this.#fetchSnapshotPage(path, table, null, pageLimit)
+          break
+        } catch (error) {
+          pageLimit = this.#snapshotRetryLimit(error, pageLimit, {
+            phase: 'snapshot_page_fetch',
+            table,
+            cursor: null,
+          })
+        }
+      }
+      this.#resetSnapshotBillingWindow()
+      const progress = this.#withIngestBilling(
+        {
+          phase: 'snapshot_begin',
+          table,
+          startWatermark: page.watermark,
+        },
+        () =>
+          this.ctx.storage.transactionSync(() =>
+            this.#wasm(() =>
+              engine_begin_snapshot_generation(
+                this.#engineDb,
+                config.schema,
+                String(page.watermark)
+              )
+            )
+          )
+      ) as SnapshotProgress
+      return { progress, page, pageLimit }
     }
 
     #ingest(upstreamPath?: string | null, forceSnapshot = false): Promise<number> {
@@ -653,21 +789,172 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
           ? this.#ingestPromise.then(() => this.#ingest(upstreamPath, true))
           : this.#ingestPromise
       }
-      this.#ingestBreaker.assertReady()
       const path = upstreamPath ?? this.#controlGet('upstreamPath')
-      if (!path) {
+      if (path === null) {
         return forceSnapshot
           ? Promise.reject(requestError('upstream path is not available'))
           : Promise.resolve(0)
       }
       this.#ingestPromise = (async () => {
+        let progress = this.#snapshotProgress()
+        this.#ingestBreaker.assertReady()
+        const startingWatermark = this.#engineState().watermark
         let total = 0
+        let pendingPage: SnapshotPage | null = null
+        let snapshotPageLimit = DEFAULT_SNAPSHOT_PAGE_ROWS
+        let snapshotCompleted = false
         for (;;) {
-          const cursor = this.#engineState()?.upstreamWatermark ?? '0'
+          if (progress?.state === 'paging') {
+            const activeProgress = progress
+            const table = activeProgress.table
+            if (table === null) {
+              throw new Error(
+                `snapshot generation ${activeProgress.generation} is paging without a table`
+              )
+            }
+            let page: SnapshotPage | null = pendingPage
+            try {
+              page ??= await this.#fetchSnapshotPage(
+                path,
+                table,
+                activeProgress.cursor,
+                snapshotPageLimit
+              )
+              const pageToApply = page
+              this.#resetSnapshotBillingWindow()
+              const nextProgress = this.#withIngestBilling(
+                {
+                  phase: 'snapshot_page_apply',
+                  generation: activeProgress.generation,
+                  table,
+                  cursor: activeProgress.cursor,
+                  pageRows: pageToApply.rows.length,
+                  pageLimit: snapshotPageLimit,
+                },
+                () =>
+                  this.ctx.storage.transactionSync(() =>
+                    this.#wasm(() =>
+                      engine_apply_snapshot_page(
+                        this.#engineDb,
+                        config.schema,
+                        activeProgress.generation,
+                        table,
+                        pageToApply.rows,
+                        pageToApply.nextCursor
+                      )
+                    )
+                  )
+              ) as SnapshotProgress
+              total += pageToApply.rows.length
+              this.#recordIngestLogicalRows(pageToApply.rows.length)
+              progress = nextProgress
+              pendingPage = null
+            } catch (error) {
+              snapshotPageLimit = this.#snapshotRetryLimit(error, snapshotPageLimit, {
+                phase: page === null ? 'snapshot_page_fetch' : 'snapshot_page_apply',
+                generation: activeProgress.generation,
+                table,
+                cursor: activeProgress.cursor,
+              })
+              pendingPage = null
+            }
+            continue
+          }
+
+          if (progress?.state === 'catching_up') {
+            const activeProgress = progress
+            const cursor = activeProgress.catchupWatermark
+            const endpoint = new URL(`${path}/changes`, 'https://upstream.invalid')
+            endpoint.searchParams.set('since', cursor)
+            endpoint.searchParams.set('limit', String(upstreamLimit))
+            const response = await this.#serviceBinding().fetch(endpoint.toString(), {
+              headers: { host: endpoint.host },
+            })
+            if (response.status === 410) {
+              const begun = await this.#beginSnapshotGeneration(path)
+              progress = begun.progress
+              pendingPage = begun.page
+              snapshotPageLimit = begun.pageLimit
+              continue
+            }
+            if (!response.ok) {
+              throw new Error(`upstream snapshot catch-up returned ${response.status}`)
+            }
+            const batch = (await response.json()) as UpstreamBatch
+            if (!Number.isSafeInteger(batch.watermark) || !Array.isArray(batch.changes)) {
+              throw new Error('invalid upstream changes response')
+            }
+            this.#resetSnapshotBillingWindow()
+            const result = this.#withIngestBilling(
+              {
+                phase: 'snapshot_catchup',
+                generation: activeProgress.generation,
+                cursor,
+                batchWatermark: batch.watermark,
+                changeRows: batch.changes.length,
+              },
+              () =>
+                this.ctx.storage.transactionSync(() =>
+                  this.#wasm(() =>
+                    engine_apply_snapshot_changes(
+                      this.#engineDb,
+                      config.schema,
+                      activeProgress.generation,
+                      batch
+                    )
+                  )
+                )
+            ) as ApplyUpstreamResult
+            total += result.applied
+            this.#recordIngestLogicalRows(result.applied)
+            if (result.caughtUp) {
+              this.#resetSnapshotBillingWindow()
+              this.#withIngestBilling(
+                {
+                  phase: 'snapshot_finalize',
+                  generation: activeProgress.generation,
+                  watermark: result.watermark,
+                },
+                () =>
+                  this.ctx.storage.transactionSync(() =>
+                    this.#wasm(() =>
+                      engine_finalize_snapshot_generation(
+                        this.#engineDb,
+                        config.schema,
+                        activeProgress.generation,
+                        String(result.watermark)
+                      )
+                    )
+                  )
+              )
+              progress = null
+              snapshotCompleted = true
+              break
+            }
+            if (String(result.watermark) === cursor) {
+              this.#tripIngest('ingestCursorStalled', {
+                phase: 'snapshot_catchup',
+                generation: activeProgress.generation,
+                cursor,
+                batchWatermark: batch.watermark,
+                changeRows: batch.changes.length,
+                applied: result.applied,
+              })
+            }
+            progress = {
+              ...progress,
+              catchupWatermark: String(result.watermark),
+            }
+            continue
+          }
+
+          const cursor = this.#engineState().upstreamWatermark
           if (forceSnapshot) {
             forceSnapshot = false
-            const rebuilt = await this.#applyUpstreamSnapshot(path, cursor, true)
-            total += rebuilt.applied
+            const begun = await this.#beginSnapshotGeneration(path)
+            progress = begun.progress
+            pendingPage = begun.page
+            snapshotPageLimit = begun.pageLimit
             continue
           }
           const endpoint = new URL(`${path}/changes`, 'https://upstream.invalid')
@@ -677,8 +964,10 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
             headers: { host: endpoint.host },
           })
           if (response.status === 410) {
-            const rebuilt = await this.#applyUpstreamSnapshot(path, cursor, false)
-            total += rebuilt.applied
+            const begun = await this.#beginSnapshotGeneration(path)
+            progress = begun.progress
+            pendingPage = begun.page
+            snapshotPageLimit = begun.pageLimit
             continue
           }
           if (!response.ok) {
@@ -704,7 +993,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
           ) as ApplyUpstreamResult
           total += result.applied
           this.#recordIngestLogicalRows(result.applied)
-          const nextCursor = this.#engineState()?.upstreamWatermark ?? cursor
+          const nextCursor = this.#engineState().upstreamWatermark
           if (batch.changes.length > 0 && String(nextCursor) === String(cursor)) {
             this.#tripIngest('ingestCursorStalled', {
               phase: 'changes',
@@ -730,7 +1019,10 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
           }
         }
         this.#recoverIngestBreaker()
-        if (total > 0) await this.#enqueueWake('__upstream__')
+        const endingWatermark = this.#engineState().watermark
+        if (snapshotCompleted || total > 0 || endingWatermark !== startingWatermark) {
+          await this.#enqueueWake('__upstream__')
+        }
         return total
       })().finally(() => {
         this.#ingestPromise = null
@@ -738,6 +1030,13 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
       return this.#ingestPromise
     }
 
+    #ingestAfterCurrent(upstreamPath: string | null): Promise<number> {
+      const current = this.#ingestPromise
+      return current
+        ? current.then(() => this.#ingest(upstreamPath))
+        : this.#ingest(upstreamPath)
+    }
+
     async #fetchDelegatedPush(
       endpoint: URL,
       headers: Headers,
@@ -804,23 +1103,6 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
       )
     }
 
-    async #runEffects(effects: DeferredEffect[]): Promise<void> {
-      for (const effect of effects) {
-        try {
-          await effect()
-        } catch (error) {
-          this.#counters.externalEffectFailures++
-          console.error(
-            JSON.stringify({
-              event: 'sync_external_effect_error',
-              hostVersion: config.hostVersion,
-              error: errorMessage(error),
-            })
-          )
-        }
-      }
-    }
-
     #enqueueWake(originClientID: string): Promise<void> {
       this.#wakeOrigins.add(originClientID)
       for (const socket of this.ctx.getWebSockets()) {
@@ -905,84 +1187,94 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
         if (!Number.isSafeInteger(transformVersion) || transformVersion < 0) {
           throw new TypeError('queryTransformVersion must be a non-negative safe integer')
         }
-        if (queryAware && body.queries) {
-          const queries = body.queries as {
-            version?: unknown
-            patch?: unknown
-          }
-          if (Array.isArray(queries.patch)) {
-            const patch = []
-            for (const operation of queries.patch) {
-              if (!operation || typeof operation !== 'object') {
-                patch.push(operation)
-                continue
-              }
-              const op = operation as Record<string, unknown>
-              if (op.op === 'put') {
-                if (!config.resolveQuery || typeof op.name !== 'string') {
-                  throw requestError('query put requires a server-resolved named query')
-                }
-                if (!Array.isArray(op.args)) {
-                  throw requestError('named query args must be an array')
-                }
-                const args = op.args as JsonValue[]
-                let ast: JsonValue
-                try {
-                  // resolveQuery may be async and needs `env` (a consumer can
-                  // delegate the transform to its app's real synced-queries
-                  // endpoint over an app service binding — authenticate runs in the
-                  // worker isolate, but the query loop runs here in the DO, so the
-                  // binding must come from the DO's own env, not a shared global).
-                  ast = await config.resolveQuery(op.name, args, claims, this.env)
-                } catch (error) {
-                  throw requestError(`unknown or unsupported named query: ${op.name}`)
+        const releaseQueryPull =
+          queryAware && config.resolveQuery
+            ? await this.#acquireQueryPullLock(
+                typeof body.clientGroupID === 'string' ? body.clientGroupID : ''
+              )
+            : null
+        let response: Record<string, unknown>
+        try {
+          if (queryAware && body.queries) {
+            const queries = body.queries as {
+              version?: unknown
+              patch?: unknown
+            }
+            if (Array.isArray(queries.patch)) {
+              const patch = []
+              for (const operation of queries.patch) {
+                if (!operation || typeof operation !== 'object') {
+                  patch.push(operation)
+                  continue
                 }
-                patch.push({
-                  op: 'put',
-                  hash: op.hash,
-                  ast,
-                  transformVersion,
-                })
-              } else patch.push(operation)
+                const op = operation as Record<string, unknown>
+                if (op.op === 'put') {
+                  if (!config.resolveQuery || typeof op.name !== 'string') {
+                    throw requestError('query put requires a server-resolved named query')
+                  }
+                  if (!Array.isArray(op.args)) {
+                    throw requestError('named query args must be an array')
+                  }
+                  const args = op.args as JsonValue[]
+                  let ast: JsonValue
+                  try {
+                    // resolveQuery may be async and needs `env` (a consumer can
+                    // delegate the transform to its app's real synced-queries
+                    // endpoint over an app service binding — authenticate runs in the
+                    // worker isolate, but the query loop runs here in the DO, so the
+                    // binding must come from the DO's own env, not a shared global).
+                    ast = await config.resolveQuery(op.name, args, claims, this.env)
+                  } catch (error) {
+                    throw requestError(`unknown or unsupported named query: ${op.name}`)
+                  }
+                  patch.push({
+                    op: 'put',
+                    hash: op.hash,
+                    ast,
+                    transformVersion,
+                  })
+                } else patch.push(operation)
+              }
+              body = { ...body, queries: { ...queries, patch } }
             }
-            body = { ...body, queries: { ...queries, patch } }
           }
-        }
-        if (queryAware) {
-          body = { ...body, _serverQueryTransformVersion: transformVersion }
-        }
-        const clientID = typeof body.clientID === 'string' ? body.clientID : ''
-        this.#pulling.add(clientID)
-        let response: Record<string, unknown>
-        try {
-          const txStarted = performance.now()
-          const duringFault = this.#takeFault('pull_during_tx')
-          response = this.ctx.storage.transactionSync(() => {
-            const result = this.#wasm(() =>
-              queryAware
-                ? engine_handle_query_pull(
-                    this.#engineDb,
-                    config.schema,
-                    this.#retainChanges(),
-                    body,
-                    claims.userID
-                  )
-                : engine_handle_pull(
-                    this.#engineDb,
-                    config.schema,
-                    this.#visibility(claims),
-                    caps,
-                    this.#retainChanges(),
-                    body,
-                    claims.userID
-                  )
-            ) as Record<string, unknown>
-            if (duringFault) throw this.#faultError(duringFault, 'pull_during_tx')
-            return result
-          })
-          transactionMs = performance.now() - txStarted
+          if (queryAware) {
+            body = { ...body, _serverQueryTransformVersion: transformVersion }
+          }
+          const clientID = typeof body.clientID === 'string' ? body.clientID : ''
+          this.#pulling.add(clientID)
+          try {
+            const txStarted = performance.now()
+            const duringFault = this.#takeFault('pull_during_tx')
+            response = this.ctx.storage.transactionSync(() => {
+              const result = this.#wasm(() =>
+                queryAware
+                  ? engine_handle_query_pull(
+                      this.#engineDb,
+                      config.schema,
+                      this.#retainChanges(),
+                      body,
+                      claims.userID
+                    )
+                  : engine_handle_pull(
+                      this.#engineDb,
+                      config.schema,
+                      this.#visibility(claims),
+                      caps,
+                      this.#retainChanges(),
+                      body,
+                      claims.userID
+                    )
+              ) as Record<string, unknown>
+              if (duringFault) throw this.#faultError(duringFault, 'pull_during_tx')
+              return result
+            })
+            transactionMs = performance.now() - txStarted
+          } finally {
+            this.#pulling.delete(clientID)
+          }
         } finally {
-          this.#pulling.delete(clientID)
+          releaseQueryPull?.()
         }
         const afterPullFault = this.#takeFault('pull_after_commit')
         if (afterPullFault) throw this.#faultError(afterPullFault, 'pull_after_commit')
@@ -995,7 +1287,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
               ).length
             : 0
         this.#counters.queryRecompilations += queryPuts
-        const state = this.#engineState()
+        const state = this.#engineStateBestEffort()
         this.#log({
           namespaceHash: namespace,
           requestKind: 'pull',
@@ -1021,14 +1313,15 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
         const status = statusOf(error)
         if (status === 409) this.#counters.resets++
         if (status === 500) this.#counters.invariantFailures++
+        const state = this.#engineStateBestEffort()
         this.#log({
           namespaceHash: namespace,
           requestKind: 'pull',
           resultClass: status === 409 ? 'reset' : 'error',
           inputCookie: body?.cookie ?? null,
           outputCookie: null,
-          retainedFloor: this.#engineState()?.floor ?? null,
-          currentWatermark: this.#engineState()?.watermark ?? null,
+          retainedFloor: state?.floor ?? null,
+          currentWatermark: state?.watermark ?? null,
           changeRowsScanned: null,
           changeRowsIncluded: 0,
           queriesRecomputed: 0,
@@ -1059,7 +1352,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
         // Workerd requires the request stream to be consumed before the DO
         // returns a response. Discard it without parsing or logging payloads.
         await request.arrayBuffer()
-        const state = this.#engineState()
+        const state = this.#engineStateBestEffort()
         this.#log({
           namespaceHash: namespace,
           requestKind: 'push',
@@ -1094,7 +1387,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
 
           const endpoint = new URL(
             `${upstreamPath ?? ''}${config.mutateUrl}`,
-            'https://upstream.invalid'
+            config.mutateOrigin ?? 'https://upstream.invalid'
           )
           const headers = new Headers(request.headers)
           headers.delete(CLAIMS_HEADER)
@@ -1105,7 +1398,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
             endpoint,
             headers,
             bytes,
-            this.#engineState()?.upstreamWatermark === '0'
+            this.#engineState().upstreamWatermark === '0'
           )
           if (!upstreamResponse.ok) {
             return new Response(upstreamResponse.body, upstreamResponse)
@@ -1134,7 +1427,18 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
                 result.id?.clientID === mutation.clientID &&
                 String(result.id?.id) === mutation.id
             )
-            if (!ack) continue
+            if (!ack) {
+              throw new Error(
+                `delegated push did not acknowledge ${mutation.clientID}:${mutation.id}`
+              )
+            }
+          }
+          // the delegated app response is causally visible through DATA by
+          // contract. start an ingest round after that response, even if an
+          // older round is still in flight, then journal lmids. every capped
+          // log prefix therefore preserves effects-before-ack.
+          await this.#ingestAfterCurrent(upstreamPath)
+          for (const mutation of plan.mutations) {
             this.ctx.storage.transactionSync(() => {
               const decision = this.#wasm(() =>
                 engine_preflight(
@@ -1163,7 +1467,6 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
               this.#wasm(() => engine_prune(this.#engineDb, this.#retainChanges()))
             )
           }
-          await this.#ingest(upstreamPath)
           return json({ pushResponse: delegatedResponse })
         } catch (error) {
           const status = statusOf(error)
@@ -1180,7 +1483,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
 
         const results: MutationResult[] = []
         for (const mutation of plan.mutations) {
-          const deferred: DeferredEffect[] = []
+          const deferred = createPostCommitEffects()
           try {
             const txStarted = performance.now()
             // consume the before-commit fault OUTSIDE the transaction it is
@@ -1191,7 +1494,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
             const preflight = await this.ctx.storage.transaction(async () => {
               // Storage transactions may retry their closure. Never carry a
               // deferred effect from an abandoned attempt into the commit.
-              deferred.length = 0
+              deferred.beginAttempt()
               const decision = this.#wasm(() =>
                 engine_preflight(
                   this.#engineDb,
@@ -1208,9 +1511,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
                 claims,
                 clientID: mutation.clientID,
                 mutationID: mutation.id,
-                defer(effect) {
-                  deferred.push(effect)
-                },
+                defer: deferred.defer,
               })
               if (beforeCommitFault)
                 throw this.#faultError(
@@ -1253,9 +1554,18 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
             // waitUntil anchors the coalescing timer across request completion,
             // while the next serialized client push can join the same batch.
             this.ctx.waitUntil(this.#enqueueWake(mutation.clientID))
-            await this.#runEffects(deferred)
+            await deferred.runAfterCommit((error) => {
+              this.#counters.externalEffectFailures++
+              console.error(
+                JSON.stringify({
+                  event: 'sync_external_effect_error',
+                  hostVersion: config.hostVersion,
+                  error: errorMessage(error),
+                })
+              )
+            })
           } catch (error) {
-            const isAppError = error instanceof MutationApplicationError
+            const isAppError = isMutationApplicationError(error)
             if (!isAppError) throw error
             this.#counters.applicationErrors++
             resultClass = 'application_error'
@@ -1301,7 +1611,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
           throw this.#faultError(afterCommitFault, 'push_after_commit_before_response')
 
         const response = this.#wasm(() => engine_assemble_push_response(results))
-        const state = this.#engineState()
+        const state = this.#engineStateBestEffort()
         this.#log({
           namespaceHash: namespace,
           requestKind: 'push',
@@ -1330,14 +1640,15 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
       } catch (error) {
         const status = statusOf(error)
         if (status === 500) this.#counters.invariantFailures++
+        const state = this.#engineStateBestEffort()
         this.#log({
           namespaceHash: namespace,
           requestKind: 'push',
           resultClass: 'error',
           inputCookie: null,
           outputCookie: null,
-          retainedFloor: this.#engineState()?.floor ?? null,
-          currentWatermark: this.#engineState()?.watermark ?? null,
+          retainedFloor: state?.floor ?? null,
+          currentWatermark: state?.watermark ?? null,
           changeRowsScanned: 0,
           changeRowsIncluded: 0,
           queriesRecomputed: 0,
@@ -1402,7 +1713,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
             heapUsedBytes: heap?.usedJSHeapSize ?? null,
             heapTotalBytes: heap?.totalJSHeapSize ?? null,
             heapLimitBytes: heap?.jsHeapSizeLimit ?? null,
-            engine: this.#engineState(),
+            engine: this.#engineStateBestEffort(),
             counters: this.#counters,
             ingestBreaker: this.#ingestBreaker.status(),
           })
@@ -1410,9 +1721,22 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
       }
       if (route === '/admin/sql') {
         return request.json().then((body) => {
-          const { query } = body as { query?: string }
+          const { params, query } = body as { params?: unknown; query?: string }
           if (typeof query !== 'string') return json({ error: 'query is required' }, 400)
-          return json({ rows: this.#directSql.query(query) })
+          try {
+            return json({ rows: this.#directSql.query(query, decodeSqlParams(params)) })
+          } catch (error) {
+            if (error instanceof TypeError && error.message.startsWith('params')) {
+              return json({ error: `invalid params: ${error.message}` }, 400)
+            }
+            if (
+              error instanceof TypeError &&
+              error.message === 'transaction SQL is host-owned and forbidden'
+            ) {
+              return json({ error: error.message }, 400)
+            }
+            throw error
+          }
         })
       }
       if (route === '/admin/invalidate') {
@@ -1427,14 +1751,14 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
         }
         return (async () => {
           try {
-            const beforeUpstreamWatermark = this.#engineState()?.upstreamWatermark ?? null
+            const beforeUpstreamWatermark = this.#engineState().upstreamWatermark
             const applied = await this.#ingest(upstreamPath, true)
             const engine = this.#engineState()
             return json({
               ok: true,
               applied,
               beforeUpstreamWatermark,
-              afterUpstreamWatermark: engine?.upstreamWatermark ?? null,
+              afterUpstreamWatermark: engine.upstreamWatermark,
               engine,
             })
           } catch (error) {
@@ -1447,12 +1771,7 @@ export function createSyncDurableObject<Env extends SyncHostEnv>(
         return json({ ok: true })
       }
       if (route === '/admin/restart') {
-        this.#bootID = crypto.randomUUID()
-        this.#hibernations++
-        this.#counters = freshCounters()
-        this.#pulling.clear()
-        this.#wakeOrigins.clear()
-        this.#wakeRecipients.clear()
+        this.ctx.abort('admin requested durable object restart')
         return json({ ok: true, bootID: this.#bootID })
       }
       if (route === '/admin/visibility') {