orez-sync-cf-host 0.5.18 → 0.5.19

package/README.md

@@ -17,6 +17,29 @@ Every SQL cursor is materialized before an await. Mutators may await only their
 `context.defer`, which runs only after commit. Application failures use the
 required second transaction to advance the LMID marker.
 
+The root `orez/cf-do` executor and this host consume the same `post-commit`
+module, so transaction retries discard effects from abandoned attempts in both
+paths.
+
+Transaction-query `ILIKE` folding is ASCII-only on Durable Object SQLite;
+non-ASCII case pairs can diverge from PostgreSQL.
+
+### Bun query compiler
+
+Wrangler loads the engine's `.wasm` import as a precompiled
+`WebAssembly.Module`. Bun consumers of `createQueryCompiler` must register the
+package loader so the same import has the same value without changing the
+compiler code:
+
+```toml
+# bunfig.toml
+preload = ["orez-sync-cf-host/bun-wasm-loader"]
+```
+
+For a single command, use
+`bun --preload orez-sync-cf-host/bun-wasm-loader <command>`. The compiler throws
+an error naming this preload when Bun resolves the `.wasm` import as a pathname.
+
 ## Wake channel and eviction
 
 `GET /<namespace>/wake?clientID=<id>&wakeToken=<capability>` upgrades to a
@@ -50,6 +73,8 @@ every socket attempt, including reconnects, so short-lived tokens are never
 reused after the wake connection drops:
 
 ```ts
+import { ensureHttpPullTransport } from 'orez/zero-http'
+
 ensureHttpPullTransport({
   origin: syncOrigin,
   pullIntervalMs: 5_000,
@@ -105,6 +130,24 @@ service or operator capability. Both `authorizeWake` and `authorizeNotify` run
 before `idFromName`, so rejected requests cannot instantiate namespace Durable
 Objects.
 
+### Consumer routing traps
+
+If an outer application router has its own namespace gate, let only `/wake` and
+`/notify` pass that outer gate. The sync worker's required `authorizeWake` and
+`authorizeNotify` callbacks then enforce the real capability checks. Do not
+bypass pull, push, or admin routes, and do not replace either callback with an
+unconditional allow.
+
+A delegated push must terminate at the application worker whose registry owns
+the named mutator. Routing it to a sync host, control-plane worker, or another
+application server with a different registry produces an authoritative error
+such as `could not find mutator <name>`. The optimistic client write may appear
+briefly, then disappear on reload and never reach peers. Route client pushes to
+the sync host only when its `mutateBinding` and `mutateUrl` delegate to the
+owning application's mutate endpoint. Preview and browser-local transports must
+stay pointed at their in-process project server unless they provide the same
+delegated route.
+
 `POST /admin/writer` with `{ "enabled": false }` durably stops pushes for that
 namespace. A stopped writer consumes and discards the request body, returns 503,
 and performs no engine or application write. Canary rollback drills must stop
@@ -119,12 +162,36 @@ not mutate a production route. These controls are mechanisms, not authorization
 to perform a production cutover.
 
 `POST /admin/resnapshot` is available only when the consumer configured an
-upstream data service. It reads that namespace's authoritative `/snapshot`,
-atomically replaces the derived application tables, then consumes `/changes`
-until caught up. Engine metadata, client last-mutation IDs, operator controls,
-and the authoritative upstream database are preserved. The JSON response
-includes before/after upstream watermarks and the number of snapshot plus
-catch-up rows applied.
+upstream data service. It reads each modeled source table through bounded
+keyset pages and commits them to a staged generation. Progress is durable, so a
+restart resumes at the recorded table and cursor. The host then catches up
+concurrent `/changes`, atomically swaps the generation into place, and bumps the
+engine epoch. Every client performs one expected full resync after cutover.
+Engine metadata, client last-mutation IDs, operator controls, and the
+authoritative upstream database are preserved. The legacy single-response
+`/snapshot` endpoint remains for small datasets and older harnesses.
+
+## Delegated service addresses
+
+`mutateBinding` selects the service binding that owns the application's mutate
+endpoint and defaults to `upstream.binding`. Set `mutateOrigin` to an exact
+absolute HTTP(S) origin when that worker's routing depends on the request
+origin. `upstream.namespacePath` may return `/` for a root-mounted data feed;
+internally that root is an empty path, while `null` alone means no upstream path
+is configured.
+
+A successful delegated mutation response has a hard causality contract: its
+committed application effects must already be readable from the configured
+upstream `/changes` feed before the application worker returns. The sync host
+then ingests through those effects, journals the acknowledged LMID after them,
+and only then returns the push response. This keeps every capped change-log
+prefix ordered so an acknowledgement cannot reach a client before its effects.
+Chat and Soot use an application-to-data service path that provides this
+ordering today. A future topology that cannot provide it must extend the
+delegated response with an upstream watermark receipt and make the host ingest
+through that receipt before finalization. Do not add a second best-effort path.
+The ordering does not add another ingest round: delegated pushes already waited
+for post-mutation ingest before returning, and now finalize after that wait.
 
 ## Counter and HTTP wire representation
 
@@ -212,4 +279,4 @@ absent when the cleanup command was run (Cloudflare returned error 10090), so no
 old probe service remains to receive traffic.
 
 The rust toolchain is pinned at the workspace root in
-[rust-toolchain.toml](/Users/n8/.worktrees/orez-rust-sync/rust-toolchain.toml).
+[`rust-toolchain.toml`](../../rust-toolchain.toml).

package/package.json

@@ -1,25 +1,36 @@
 {
   "name": "orez-sync-cf-host",
-  "version": "0.5.18",
+  "version": "0.5.19",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./post-commit": "./src/post-commit.ts",
+    "./mutation-error": {
+      "types": "./src/mutation-error.ts",
+      "import": "./src/mutation-error.ts"
+    },
+    "./bun-wasm-loader": "./src/bun-wasm-loader.ts",
+    "./query-compiler": "./src/query-compiler.ts",
+    "./transaction-query": "./src/transaction-query.ts"
   },
   "scripts": {
     "build:wasm": "wasm-pack build ../../crates/sync-wasm --target web --release --out-dir ../../packages/sync-cf-host/src/generated --out-name sync_wasm && rm -f src/generated/.gitignore && bun scripts/write-wasm-module-type.ts",
     "build:wasm:platform": "wasm-pack build ../../crates/sync-wasm --target web --release --out-dir ../../packages/sync-cf-host/src/generated --out-name sync_wasm -- --features platform-probes && rm -f src/generated/.gitignore && bun scripts/write-wasm-module-type.ts",
     "bundle": "bun run build:wasm && wrangler deploy --dry-run --outdir dist",
     "measure": "bun run build:wasm && bun measure.mjs",
-    "test": "bun run test:config && bun run test:platform && bun run test:integration && bun run test:ingest && bun run test:restart",
-    "test:config": "bun test config.test.mjs write-safeguards.test.mjs",
+    "test": "bun run test:config && bun run test:query-compiler && bun run test:platform && bun run test:integration && bun run test:ingest && bun run test:restart",
+    "test:config": "bun test config.test.mjs write-safeguards.test.mjs mutation-error.test.mjs post-commit.test.mjs",
     "test:integration": "bun run build:wasm && bun integration-test.mjs",
     "test:ingest": "bun run build:wasm && bun ingest-test.mjs",
+    "test:query-compiler": "bun run build:wasm && bun test --preload orez-sync-cf-host/bun-wasm-loader query-compiler.test.mjs",
     "test:restart": "bun restart-test.mjs",
     "test:platform": "bun run build:wasm:platform && bun platform-test.mjs",
     "typecheck": "bun run build:wasm:platform && tsc --noEmit"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "4.20260617.1",
+    "@types/bun": "1.3.14",
+    "@types/node": "22.19.10",
     "typescript": "5.9.3",
     "workerd": "1.20260617.1",
     "wrangler": "4.103.0"

package/src/bun-wasm-loader.ts

@@ -0,0 +1,16 @@
+import { Buffer } from 'node:buffer'
+
+import { file, plugin } from 'bun'
+
+plugin({
+  name: 'orez-sync-cf-host-wasm',
+  setup(build) {
+    build.onLoad({ filter: /sync_wasm_bg\.wasm$/ }, async ({ path }) => {
+      const bytes = Buffer.from(await file(path).arrayBuffer()).toString('base64')
+      return {
+        contents: `export default new WebAssembly.Module(Uint8Array.fromBase64('${bytes}'))`,
+        loader: 'js',
+      }
+    })
+  },
+})

package/src/config.ts

@@ -89,5 +89,14 @@ export function validateSyncHostConfig<Env extends SyncHostEnv>(
         throw new TypeError(`delegatedPushRetry.${name} must be a positive safe integer`)
     }
   }
+  if (config.transactionQueryBudget) {
+    for (const [name, value] of Object.entries(config.transactionQueryBudget)) {
+      if (!Number.isSafeInteger(value) || Number(value) < 1) {
+        throw new TypeError(
+          `transactionQueryBudget.${name} must be a positive safe integer`
+        )
+      }
+    }
+  }
   return config
 }

package/src/generated/sync_wasm.d.ts

@@ -37,7 +37,7 @@ export function engine_begin_snapshot_generation(db: any, schema: any, start_wat
  * Compile a validated Zero query AST for a consumer mutator's transactional
  * `tx.run(...)`. Execution remains in the host-owned application transaction.
  */
-export function engine_compile_query(schema: any, ast: any): any;
+export function engine_compile_query(schema: any, ast: any, format: any): any;
 
 export function engine_finalize(db: any, client_group_id: string, client_id: string, mutation_id: string): void;
 
@@ -109,7 +109,7 @@ export interface InitOutput {
     readonly engine_apply_upstream_snapshot: (a: any, b: any, c: any) => [number, number, number];
     readonly engine_assemble_push_response: (a: any) => [number, number, number];
     readonly engine_begin_snapshot_generation: (a: any, b: any, c: number, d: number) => [number, number, number];
-    readonly engine_compile_query: (a: any, b: any) => [number, number, number];
+    readonly engine_compile_query: (a: any, b: any, c: any) => [number, number, number];
     readonly engine_finalize: (a: any, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
     readonly engine_finalize_snapshot_generation: (a: any, b: any, c: number, d: number, e: number, f: number) => [number, number, number];
     readonly engine_handle_pull: (a: any, b: any, c: any, d: any, e: number, f: number, g: any, h: number, i: number) => [number, number, number];

package/src/generated/sync_wasm.js

@@ -111,10 +111,11 @@ export function engine_begin_snapshot_generation(db, schema, start_watermark) {
  * `tx.run(...)`. Execution remains in the host-owned application transaction.
  * @param {any} schema
  * @param {any} ast
+ * @param {any} format
  * @returns {any}
  */
-export function engine_compile_query(schema, ast) {
-    const ret = wasm.engine_compile_query(schema, ast);
+export function engine_compile_query(schema, ast, format) {
+    const ret = wasm.engine_compile_query(schema, ast, format);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }

package/src/host.ts

@@ -1,13 +1,21 @@
 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_assemble_push_response,
   engine_begin_snapshot_generation,
-  engine_compile_query,
   engine_finalize,
   engine_finalize_snapshot_generation,
   engine_handle_pull,
@@ -23,15 +31,7 @@ import {
   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,
@@ -40,7 +40,6 @@ import {
 } from './write-safeguards.js'
 
 import type {
-  DeferredEffect,
   JsonValue,
   NormalizedClaims,
   PullCaps,
@@ -48,8 +47,6 @@ 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'
@@ -320,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
@@ -368,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(() => {
@@ -1030,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,
@@ -1096,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()) {
@@ -1437,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(
@@ -1466,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)
@@ -1483,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
@@ -1494,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,
@@ -1511,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(
@@ -1556,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'
@@ -1714,11 +1721,14 @@ 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)
           try {
-            return json({ rows: this.#directSql.query(query) })
+            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'

package/src/index.ts

@@ -1,5 +1,17 @@
 export { createSyncDurableObject, createSyncWorker } from './host.js'
-export { MutationApplicationError, registerMutators } from './types.js'
+export { createQueryCompiler } from './query-compiler.js'
+export {
+  MutationApplicationError,
+  isMutationApplicationError,
+  registerMutators,
+} from './types.js'
+export {
+  DEFAULT_TRANSACTION_QUERY_BUDGET,
+  TransactionQueryBudgetError,
+  executeTransactionQueryPlan,
+  executeTransactionQueryPlanAsync,
+} from './transaction-query.js'
+
 export type {
   DeferredEffect,
   JsonPrimitive,
@@ -20,3 +32,16 @@ export type {
   VisibilityFilter,
   ZeroSchemaConfig,
 } from './types.js'
+export type {
+  CompiledTransactionQueryNode,
+  CompiledTransactionQueryPlan,
+  CompiledTransactionQueryRelationship,
+  TransactionQueryBinding,
+  TransactionQueryBudget,
+  TransactionQueryColumn,
+  TransactionQueryColumnType,
+  TransactionQueryExecutionOptions,
+  TransactionQueryFormat,
+  TransactionQueryWireValue,
+} from './transaction-query.js'
+export type { TransactionQueryCompiler } from './query-compiler.js'

package/src/ingest-harness-worker.ts

@@ -24,6 +24,7 @@ type Fetcher = { fetch(input: string | Request, init?: RequestInit): Promise<Res
 interface Env extends SyncHostEnv {
   DATA: Fetcher
   APP: Fetcher
+  CAPPED_SYNC_DO: DurableObjectNamespace
   UPSTREAM_DO: DurableObjectNamespace
 }
 
@@ -35,6 +36,11 @@ const heldSnapshots = new Set<string>()
 const holdSnapshotsAfterCursor = new Set<string>()
 const activeSnapshots = new Set<string>()
 const snapshotLimits = new Map<string, number[]>()
+const heldDelegatedPushes = new Set<string>()
+const activeDelegatedPushes = new Set<string>()
+const completedDelegatedPushes = new Set<string>()
+const heldChangeResponses = new Set<string>()
+const activeHeldChangeResponses = new Set<string>()
 let delegatedFailuresRemaining = 0
 let delegatedAttempts = 0
 let delegatedPushFailedRemaining = 0
@@ -81,6 +87,11 @@ const config: SyncHostConfig<Env> = {
 }
 
 export const SyncDurableObject = createSyncDurableObject(config)
+const cappedConfig: SyncHostConfig<Env> = {
+  ...config,
+  caps: { maxChangeRows: 10_000, maxChangeBytes: 1 },
+}
+export const CappedSyncDurableObject = createSyncDurableObject(cappedConfig)
 export { ZeroDO }
 
 async function upstreamFetch(request: Request, env: Env): Promise<Response> {
@@ -251,6 +262,14 @@ export class DataService extends WorkerEntrypoint<Env> {
       )
     }
     const response = await upstreamFetch(request, this.env)
+    if (pathname.endsWith('/changes') && heldChangeResponses.has(namespace)) {
+      activeHeldChangeResponses.add(namespace)
+      try {
+        while (heldChangeResponses.has(namespace)) await scheduler.wait(10)
+      } finally {
+        activeHeldChangeResponses.delete(namespace)
+      }
+    }
     if (pathname.endsWith('/snapshot')) {
       const limit = Number(url.searchParams.get('limit'))
       if (Number.isSafeInteger(limit)) {
@@ -281,7 +300,7 @@ export class DataService extends WorkerEntrypoint<Env> {
 }
 
 export class AppService extends WorkerEntrypoint<Env> {
-  fetch(request: Request): Promise<Response> {
+  async fetch(request: Request): Promise<Response> {
     delegatedUrl = request.url
     if (!new URL(request.url).pathname.endsWith('/api/zero/push')) {
       return Promise.resolve(
@@ -313,14 +332,81 @@ export class AppService extends WorkerEntrypoint<Env> {
         Response.json({ error: 'synthetic delegated push failure' }, { status: 503 })
       )
     }
-    return upstreamFetch(request, this.env)
+    if (heldDelegatedPushes.has(namespace)) {
+      activeDelegatedPushes.add(namespace)
+      try {
+        while (heldDelegatedPushes.has(namespace)) await scheduler.wait(10)
+      } finally {
+        activeDelegatedPushes.delete(namespace)
+      }
+    }
+    const push = (await request.clone().json()) as {
+      mutations?: Array<{ clientID?: string; id?: number; name?: string }>
+    }
+    const cleanupIDs = new Set(
+      (push.mutations ?? [])
+        .filter((mutation) => mutation.name === '_zero_cleanupResults')
+        .map((mutation) => `${mutation.clientID}:${mutation.id}`)
+    )
+    const response = await upstreamFetch(request, this.env)
+    completedDelegatedPushes.add(namespace)
+    if (response.ok && cleanupIDs.size > 0) {
+      const body = (await response.json()) as {
+        mutations?: Array<{ id?: { clientID?: string; id?: number } }>
+        pushResponse?: {
+          mutations?: Array<{ id?: { clientID?: string; id?: number } }>
+        }
+      }
+      const mutations = body.pushResponse?.mutations ?? body.mutations
+      if (Array.isArray(mutations)) {
+        const filtered = mutations.filter(
+          (mutation) => !cleanupIDs.has(`${mutation.id?.clientID}:${mutation.id?.id}`)
+        )
+        if (body.pushResponse) body.pushResponse.mutations = filtered
+        else body.mutations = filtered
+      }
+      return Response.json(body, { status: response.status })
+    }
+    return response
   }
 }
 
 const syncWorker = createSyncWorker(config)
+const cappedSyncWorker = createSyncWorker(cappedConfig)
 export default {
   fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
     const url = new URL(request.url)
+    if (url.pathname.startsWith('/delegated-ingest-control/')) {
+      const namespace = url.pathname.slice('/delegated-ingest-control/'.length)
+      if (request.method === 'GET') {
+        return Promise.resolve(
+          Response.json({
+            appHeld: heldDelegatedPushes.has(namespace),
+            appActive: activeDelegatedPushes.has(namespace),
+            appCompleted: completedDelegatedPushes.has(namespace),
+            changesHeld: heldChangeResponses.has(namespace),
+            changesActive: activeHeldChangeResponses.has(namespace),
+          })
+        )
+      }
+      return request
+        .json()
+        .catch(() => ({}))
+        .then((body) => {
+          if ((body as { appHeld?: unknown }).appHeld === true) {
+            heldDelegatedPushes.add(namespace)
+            completedDelegatedPushes.delete(namespace)
+          } else if ((body as { appHeld?: unknown }).appHeld === false) {
+            heldDelegatedPushes.delete(namespace)
+          }
+          if ((body as { changesHeld?: unknown }).changesHeld === true) {
+            heldChangeResponses.add(namespace)
+          } else if ((body as { changesHeld?: unknown }).changesHeld === false) {
+            heldChangeResponses.delete(namespace)
+          }
+          return Response.json({ ok: true, namespace })
+        })
+    }
     if (url.pathname.startsWith('/snapshot-control/')) {
       const namespace = url.pathname.slice('/snapshot-control/'.length)
       if (request.method === 'GET') {
@@ -431,6 +517,15 @@ export default {
           })
         })
     }
+    if (url.pathname.startsWith('/capped/')) {
+      url.pathname = url.pathname.slice('/capped'.length)
+      const cappedEnv = { ...env, SYNC_DO: env.CAPPED_SYNC_DO }
+      return cappedSyncWorker.fetch!(
+        new Request(url, request) as never,
+        cappedEnv,
+        ctx
+      ) as Promise<Response>
+    }
     if (url.pathname.startsWith('/upstream/')) {
       url.pathname = url.pathname.slice('/upstream'.length)
       return upstreamFetch(new Request(url, request), env)

package/src/mutation-error.ts

@@ -0,0 +1,28 @@
+// the app-rejection contract shared by every orez sync host and by
+// protocol-neutral authoring layers (on-zero adapters). classification is
+// STRUCTURAL, never instanceof: adapters must not depend on orez to reject a
+// mutation, and instanceof breaks across package copies (dual-package
+// installs, --into tarballs, workspace duplication). any error whose name is
+// 'MutationApplicationError' with string details/message is claiming this
+// contract deliberately.
+export class MutationApplicationError extends Error {
+  constructor(
+    readonly details: string,
+    message = details
+  ) {
+    super(message)
+    this.name = 'MutationApplicationError'
+  }
+}
+
+export function isMutationApplicationError(
+  error: unknown
+): error is { name: string; message: string; details: string } {
+  if (typeof error !== 'object' || error === null) return false
+  const shaped = error as { name?: unknown; message?: unknown; details?: unknown }
+  return (
+    shaped.name === 'MutationApplicationError' &&
+    typeof shaped.message === 'string' &&
+    typeof shaped.details === 'string'
+  )
+}