orez-sync-cf-host 0.5.19 → 0.5.21

package/dist/host.js

@@ -0,0 +1,1512 @@
+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_finalize, engine_finalize_snapshot_generation, engine_handle_pull, engine_handle_query_pull, engine_init_query_schema, engine_init_schema, engine_invalidate, engine_memory_bytes, engine_preflight, engine_prune, engine_push_validate, engine_read_snapshot_progress, engine_record_app_error, engine_state, engine_version, } from './wasm.js';
+import { IngestBreakerError, IngestCircuitBreaker, retryDelayMs, shouldRetryDelegatedPush, } from './write-safeguards.js';
+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 = {
+    maxChangeRows: 10_000,
+    maxChangeBytes: 2_000_000,
+};
+function freshCounters() {
+    return {
+        pulls: 0,
+        pushes: 0,
+        resets: 0,
+        applicationErrors: 0,
+        invariantFailures: 0,
+        retentionRuns: 0,
+        queryRecompilations: 0,
+        wasmBoundaryCalls: 0,
+        wakeFrames: 0,
+        wakeBatches: 0,
+        externalEffectFailures: 0,
+    };
+}
+function json(value, status = 200) {
+    return Response.json(value, {
+        status,
+        headers: { 'cache-control': 'no-store' },
+    });
+}
+function isStructuredPushFailed(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const body = value;
+    return (body.kind === 'PushFailed' &&
+        typeof body.origin === 'string' &&
+        typeof body.reason === 'string' &&
+        typeof body.message === 'string' &&
+        Array.isArray(body.mutationIDs));
+}
+function statusOf(error) {
+    if (typeof error === 'object' && error !== null && 'status' in error) {
+        const status = Number(error.status);
+        if (Number.isInteger(status) && status >= 400 && status <= 599)
+            return status;
+    }
+    return 500;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function errorBody(error) {
+    if (error instanceof IngestBreakerError) {
+        return {
+            error: error.error,
+            windowRows: error.windowRows,
+            budget: error.budget,
+            retryAfterMs: error.retryAfterMs,
+        };
+    }
+    return { error: errorMessage(error) };
+}
+function requestError(message, status = 400) {
+    return Object.assign(new Error(message), { status });
+}
+async function requestJson(request) {
+    try {
+        return await request.json();
+    }
+    catch {
+        throw requestError('invalid JSON request body');
+    }
+}
+async function requestObject(request) {
+    const value = await requestJson(request);
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw requestError('request body must be a JSON object');
+    return value;
+}
+function routeAfterNamespace(pathname) {
+    const [, , ...parts] = pathname.split('/');
+    return `/${parts.join('/')}`;
+}
+function claimsFromRequest(request) {
+    const encoded = request.headers.get(CLAIMS_HEADER);
+    if (!encoded)
+        return null;
+    try {
+        const value = JSON.parse(decodeURIComponent(encoded));
+        return value && typeof value.userID === 'string' && value.userID.length > 0
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function namespaceHash(namespace) {
+    const bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(namespace));
+    return Array.from(new Uint8Array(bytes).slice(0, 8), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+function socketAttachment(socket) {
+    const value = socket.deserializeAttachment();
+    return value && typeof value.clientID === 'string' ? value : null;
+}
+// Closing a socket that is already closed/closing throws, and a throw inside a
+// hibernatable WebSocket handler aborts the DO. Swallow it: the socket is going
+// away regardless.
+function socketCloseQuietly(socket, code, reason) {
+    try {
+        socket.close(code, reason);
+    }
+    catch {
+        // already closing/closed, or workerd rejected the code — nothing to do
+    }
+}
+/**
+ * Create the consumer-facing Worker router. Authentication happens here; the
+ * Durable Object receives only normalized claims over a binding-private header.
+ */
+export function createSyncWorker(config) {
+    validateSyncHostConfig(config);
+    return {
+        async fetch(request, env) {
+            const namespace = config.namespace(request);
+            if (!namespace)
+                return new Response('orez sync-cf-host', { status: 200 });
+            const route = routeAfterNamespace(new URL(request.url).pathname);
+            const isAdmin = route.startsWith('/admin/');
+            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;
+                if (!authorized)
+                    return json({ error: 'forbidden' }, 403);
+            }
+            const headers = new Headers(request.headers);
+            headers.delete(CLAIMS_HEADER);
+            headers.delete(NAMESPACE_HEADER);
+            headers.delete(UPSTREAM_PATH_HEADER);
+            if (!isAdmin && route !== '/wake' && route !== '/notify') {
+                const claims = await config.authenticate(request, env);
+                if (!claims)
+                    return json({ error: 'missing authentication' }, 401);
+                headers.set(CLAIMS_HEADER, encodeURIComponent(JSON.stringify(claims)));
+            }
+            headers.set(NAMESPACE_HEADER, await namespaceHash(namespace));
+            if (config.upstream) {
+                const namespacePath = typeof config.upstream.namespacePath === 'function'
+                    ? config.upstream.namespacePath(namespace)
+                    : config.upstream.namespacePath;
+                if (!namespacePath.startsWith('/')) {
+                    return json({ error: 'upstream namespacePath must be an absolute path' }, 500);
+                }
+                headers.set(UPSTREAM_PATH_HEADER, namespacePath.replace(/\/$/, ''));
+            }
+            const forwarded = new Request(request, { headers });
+            const id = env.SYNC_DO.idFromName(namespace);
+            return env.SYNC_DO.get(id).fetch(forwarded);
+        },
+    };
+}
+/** Create the namespace Durable Object class for one bundled consumer config. */
+export function createSyncDurableObject(config) {
+    validateSyncHostConfig(config);
+    const compileQuery = createQueryCompiler(config.schema);
+    const defaultRetainChanges = String(config.retainChanges ?? 4_096);
+    const caps = validatePullCaps({ ...DEFAULT_CAPS, ...config.caps });
+    const idleTeardownMs = config.idleTeardownMs ?? 5_000;
+    // A CF fan-out wakes every client into an HTTP pull. Give concurrent writer
+    // requests a real batching window so a storm burst creates one pull wave.
+    const wakeCoalesceMs = config.wakeCoalesceMs ?? 25;
+    const upstreamIntervalMs = config.upstream?.intervalMs ?? 15_000;
+    const upstreamLimit = config.upstream?.changeLimit ?? 1_000;
+    const ingestBudgetRows = config.upstream?.ingestBudgetRows ?? 150_000;
+    const ingestBudgetWindowMs = config.upstream?.ingestBudgetWindowMs ?? 5 * 60_000;
+    const ingestBackoffMs = config.upstream?.ingestBackoffMs ?? 1_000;
+    const ingestMaxBackoffMs = config.upstream?.ingestMaxBackoffMs ?? 60_000;
+    const delegateMaxAttempts = config.delegatedPushRetry?.maxAttempts ?? 3;
+    const delegateInitialBackoffMs = config.delegatedPushRetry?.initialBackoffMs ?? 100;
+    const delegateMaxBackoffMs = config.delegatedPushRetry?.maxBackoffMs ?? 1_000;
+    const delegateTimeoutMs = config.delegatedPushRetry?.timeoutMs ?? 5_000;
+    return class SyncDurableObject extends DurableObject {
+        #engineDb;
+        #directSql;
+        #mutatorSql;
+        #bootID = crypto.randomUUID();
+        #lastRequestAt = 0;
+        #hibernations = 0;
+        #dropNextPushResponse = false;
+        #counters = freshCounters();
+        #pulling = new Set();
+        #wakeOrigins = new Set();
+        #wakeRecipients = new Set();
+        #wakePromise = null;
+        #ingestPromise = null;
+        #queryPullLocks = new Map();
+        #recordingIngestBillable = false;
+        #ingestBreaker = new IngestCircuitBreaker({
+            budgetRows: ingestBudgetRows,
+            windowMs: ingestBudgetWindowMs,
+            initialBackoffMs: ingestBackoffMs,
+            maxBackoffMs: ingestMaxBackoffMs,
+            now: () => Date.now(),
+        });
+        constructor(ctx, env) {
+            super(ctx, env);
+            const recordRowsWritten = (rows) => {
+                if (this.#recordingIngestBillable)
+                    this.#ingestBreaker.recordBillable(rows);
+            };
+            this.#engineDb = new SqlStorageSyncDb(ctx.storage.sql, recordRowsWritten);
+            this.#directSql = new SqlStorageDirect(ctx.storage.sql, recordRowsWritten);
+            this.#mutatorSql = new SqlStorageMutatorTransaction(this.#directSql, (ast, format) => this.#wasm(() => compileQuery(ast, format)), config.transactionQueryBudget);
+            ctx.blockConcurrencyWhile(async () => {
+                ctx.storage.transactionSync(() => {
+                    config.initialize(this.#directSql);
+                    this.#directSql.exec(`CREATE TABLE IF NOT EXISTS _zsync_host_control (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+          )`);
+                    this.#directSql.exec("INSERT OR IGNORE INTO _zsync_host_control (key, value) VALUES ('writerEnabled', '1')");
+                    const ingestBreakerReason = this.#controlGet('ingestBreakerReason');
+                    if (ingestBreakerReason === 'ingestBudgetExceeded' ||
+                        ingestBreakerReason === 'ingestCursorStalled') {
+                        this.#ingestBreaker.restore(ingestBreakerReason, Number(this.#controlGet('ingestBreakerRetryAt')), Number(this.#controlGet('ingestBreakerTrips')));
+                    }
+                    this.#wasm(() => engine_init_schema(this.#engineDb, config.schema));
+                    if (config.queryAware || config.resolveQuery)
+                        this.#wasm(() => engine_init_query_schema(this.#engineDb));
+                });
+            });
+        }
+        #armUpstreamAlarm() {
+            if (!config.upstream)
+                return;
+            this.ctx.waitUntil((async () => {
+                if ((await this.ctx.storage.getAlarm()) === null) {
+                    await this.ctx.storage.setAlarm(Date.now() + upstreamIntervalMs);
+                }
+            })());
+        }
+        #wasm(call) {
+            this.#counters.wasmBoundaryCalls++;
+            return call();
+        }
+        async #acquireQueryPullLock(clientGroupID) {
+            const previous = this.#queryPullLocks.get(clientGroupID);
+            let release;
+            const current = new Promise((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) {
+            if (this.#lastRequestAt > 0 && now - this.#lastRequestAt >= idleTeardownMs) {
+                this.#bootID = crypto.randomUUID();
+                this.#hibernations++;
+                this.#counters = freshCounters();
+                this.#pulling.clear();
+                this.#wakeOrigins.clear();
+                this.#wakeRecipients.clear();
+                this.#wakePromise = null;
+            }
+            this.#lastRequestAt = now;
+        }
+        #visibility(claims) {
+            if (!config.visibility || !this.#visibilityEnabled())
+                return null;
+            return {
+                rowLocal: typeof config.visibility.rowLocal === 'function'
+                    ? config.visibility.rowLocal(claims)
+                    : config.visibility.rowLocal,
+                filters: Object.keys(config.schema.tables).flatMap((table) => {
+                    const filter = config.visibility?.filter(table, claims);
+                    return filter
+                        ? [{ table, sql: filter.sql, params: [...(filter.params ?? [])] }]
+                        : [];
+                }),
+            };
+        }
+        // the admin-set namespace knobs (writer, visibility, query-aware,
+        // retention) live in _zsync_host_control, NOT in instance fields: a real
+        // eviction recreates this instance, and an in-memory override silently
+        // reverting to the config default mid-run turns a query-aware namespace
+        // back into a baseline one — the client keeps re-sending its desired-query
+        // patch, the host ignores it, and every pull answers {unchanged:true}
+        // forever.
+        #controlGet(key) {
+            const row = this.#directSql.query('SELECT value FROM _zsync_host_control WHERE key = ?', [key])[0];
+            return row?.value ?? null;
+        }
+        #controlSet(key, value) {
+            this.#directSql.exec('INSERT INTO _zsync_host_control (key, value) VALUES (?, ?) ' +
+                'ON CONFLICT(key) DO UPDATE SET value = excluded.value', [key, value]);
+        }
+        #controlDelete(...keys) {
+            if (keys.length === 0)
+                return;
+            this.#directSql.exec(`DELETE FROM _zsync_host_control WHERE key IN (${keys.map(() => '?').join(', ')})`, keys);
+        }
+        #persistIngestBreaker() {
+            const status = this.#ingestBreaker.status();
+            if (!status.reason || status.retryAt === null)
+                return;
+            this.#controlSet('ingestBreakerReason', status.reason);
+            this.#controlSet('ingestBreakerRetryAt', String(status.retryAt));
+            this.#controlSet('ingestBreakerTrips', String(status.consecutiveTrips));
+        }
+        #recoverIngestBreaker() {
+            const wasTripped = this.#ingestBreaker.status().reason !== null;
+            this.#ingestBreaker.recovered();
+            if (wasTripped) {
+                this.#controlDelete('ingestBreakerReason', 'ingestBreakerRetryAt', 'ingestBreakerTrips');
+            }
+        }
+        #writerEnabled() {
+            return this.#controlGet('writerEnabled') === '1';
+        }
+        #visibilityEnabled() {
+            const value = this.#controlGet('visibilityEnabled');
+            return value === null ? (config.visibilityEnabled ?? false) : value === '1';
+        }
+        #queryAwareOverride() {
+            const value = this.#controlGet('queryAwareOverride');
+            return value === null ? null : value === '1';
+        }
+        #retainChanges() {
+            return this.#controlGet('retainChanges') ?? defaultRetainChanges;
+        }
+        #takeFault(point) {
+            if (this.#controlGet('faultPoint') !== point)
+                return null;
+            const kind = this.#controlGet('faultKind');
+            this.#directSql.exec("DELETE FROM _zsync_host_control WHERE key IN ('faultPoint', 'faultKind')");
+            return kind === 'quota' ? 'quota' : 'error';
+        }
+        #faultError(kind, point) {
+            return requestError(`injected ${kind} fault at ${point}`, kind === 'quota' ? 507 : 500);
+        }
+        #engineState() {
+            return this.#wasm(() => engine_state(this.#engineDb));
+        }
+        #engineStateBestEffort() {
+            try {
+                return this.#engineState();
+            }
+            catch {
+                return null;
+            }
+        }
+        #serviceBinding(name = config.upstream?.binding) {
+            const value = name
+                ? this.env[name]
+                : undefined;
+            if (!value || typeof value.fetch !== 'function') {
+                throw requestError(`missing upstream service binding: ${name ?? '(not configured)'}`, 500);
+            }
+            return value;
+        }
+        async #upstreamWriteBudgetStatus() {
+            if (!config.upstream)
+                return json({ error: 'upstream is not configured' }, 404);
+            const path = this.#controlGet('upstreamPath');
+            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 },
+            });
+            if (!response.ok) {
+                return json({
+                    error: 'upstream write-budget status unavailable',
+                    upstreamStatus: response.status,
+                }, 502);
+            }
+            return json(await response.json());
+        }
+        #rememberUpstreamPath(request) {
+            if (!config.upstream)
+                return null;
+            const path = request.headers.get(UPSTREAM_PATH_HEADER);
+            if (path !== null) {
+                this.#controlSet('upstreamPath', path);
+                return path;
+            }
+            return this.#controlGet('upstreamPath');
+        }
+        #tripIngest(reason, fields) {
+            try {
+                return this.#ingestBreaker.trip(reason);
+            }
+            catch (error) {
+                this.#persistIngestBreaker();
+                const status = this.#ingestBreaker.status();
+                console.error(JSON.stringify({
+                    event: 'sync_upstream_ingest_breaker_tripped',
+                    ...status,
+                    reason,
+                    ...fields,
+                }));
+                throw error;
+            }
+        }
+        #recordIngestLogicalRows(rows) {
+            this.#ingestBreaker.recordLogical(rows);
+        }
+        #withIngestBilling(fields, apply) {
+            this.#recordingIngestBillable = true;
+            try {
+                return apply();
+            }
+            catch (error) {
+                this.#recordingIngestBillable = false;
+                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();
+                    console.error(JSON.stringify({
+                        event: 'sync_upstream_ingest_breaker_tripped',
+                        ...status,
+                        reason: 'ingestBudgetExceeded',
+                        ...fields,
+                    }));
+                }
+                throw error;
+            }
+            finally {
+                this.#recordingIngestBillable = false;
+            }
+        }
+        #snapshotProgress() {
+            return this.#wasm(() => engine_read_snapshot_progress(this.#engineDb));
+        }
+        #resetSnapshotBillingWindow() {
+            // 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, limit, fields) {
+            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, table, cursor, limit) {
+            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 requestError(`upstream snapshot page returned ${response.status}`, response.status >= 500 ? 502 : response.status);
+            }
+            const page = (await response.json());
+            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;
+        }
+        async #beginSnapshotGeneration(path) {
+            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;
+            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)))));
+            return { progress, page, pageLimit };
+        }
+        #ingest(upstreamPath, forceSnapshot = false) {
+            if (!config.upstream) {
+                return forceSnapshot
+                    ? Promise.reject(requestError('upstream is not configured'))
+                    : Promise.resolve(0);
+            }
+            if (this.#ingestPromise) {
+                return forceSnapshot
+                    ? this.#ingestPromise.then(() => this.#ingest(upstreamPath, true))
+                    : this.#ingestPromise;
+            }
+            const path = upstreamPath ?? this.#controlGet('upstreamPath');
+            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 = null;
+                let snapshotPageLimit = DEFAULT_SNAPSHOT_PAGE_ROWS;
+                let snapshotCompleted = false;
+                for (;;) {
+                    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 = 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))));
+                            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());
+                        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))));
+                        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 begun = await this.#beginSnapshotGeneration(path);
+                        progress = begun.progress;
+                        pendingPage = begun.page;
+                        snapshotPageLimit = begun.pageLimit;
+                        continue;
+                    }
+                    const endpoint = new URL(`${path}/changes`, 'https://upstream.invalid');
+                    endpoint.searchParams.set('watermark', 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 changes returned ${response.status}`);
+                    }
+                    const batch = (await response.json());
+                    if (!Number.isSafeInteger(batch.watermark) || !Array.isArray(batch.changes)) {
+                        throw new Error('invalid upstream changes response');
+                    }
+                    const result = this.#withIngestBilling({
+                        phase: 'changes',
+                        cursor,
+                        batchWatermark: batch.watermark,
+                        changeRows: batch.changes.length,
+                    }, () => this.ctx.storage.transactionSync(() => this.#wasm(() => engine_apply_upstream(this.#engineDb, config.schema, batch))));
+                    total += result.applied;
+                    this.#recordIngestLogicalRows(result.applied);
+                    const nextCursor = this.#engineState().upstreamWatermark;
+                    if (batch.changes.length > 0 && String(nextCursor) === String(cursor)) {
+                        this.#tripIngest('ingestCursorStalled', {
+                            phase: 'changes',
+                            cursor,
+                            batchWatermark: batch.watermark,
+                            changeRows: batch.changes.length,
+                            applied: result.applied,
+                        });
+                    }
+                    if (result.caughtUp)
+                        break;
+                    // a page can legitimately apply zero rows while still advancing the
+                    // watermark: the engine consumes changes for tables this host does not
+                    // model (subset replica) without materializing them. only a page that
+                    // neither applied nor advanced is genuinely stalled.
+                    if (result.applied === 0 && String(nextCursor) === String(cursor)) {
+                        this.#tripIngest('ingestCursorStalled', {
+                            phase: 'changes',
+                            cursor,
+                            batchWatermark: batch.watermark,
+                            changeRows: batch.changes.length,
+                            applied: result.applied,
+                        });
+                    }
+                }
+                this.#recoverIngestBreaker();
+                const endingWatermark = this.#engineState().watermark;
+                if (snapshotCompleted || total > 0 || endingWatermark !== startingWatermark) {
+                    await this.#enqueueWake('__upstream__');
+                }
+                return total;
+            })().finally(() => {
+                this.#ingestPromise = null;
+            });
+            return this.#ingestPromise;
+        }
+        #ingestAfterCurrent(upstreamPath) {
+            const current = this.#ingestPromise;
+            return current
+                ? current.then(() => this.#ingest(upstreamPath))
+                : this.#ingest(upstreamPath);
+        }
+        async #fetchDelegatedPush(endpoint, headers, body, provisioning = false) {
+            const binding = this.#serviceBinding(config.mutateBinding ?? config.upstream?.binding);
+            let lastError = null;
+            for (let attempt = 1; attempt <= delegateMaxAttempts; attempt++) {
+                let response = null;
+                try {
+                    response = await binding.fetch(endpoint.toString(), {
+                        method: 'POST',
+                        headers,
+                        body,
+                        signal: AbortSignal.timeout(provisioning ? Math.max(delegateTimeoutMs, 25_000) : delegateTimeoutMs),
+                    });
+                }
+                catch (error) {
+                    lastError = error;
+                }
+                if (!shouldRetryDelegatedPush(response?.status ?? null, attempt, delegateMaxAttempts)) {
+                    if (response)
+                        return response;
+                    throw lastError;
+                }
+                await response?.body?.cancel();
+                const delayMs = retryDelayMs(attempt, delegateInitialBackoffMs, delegateMaxBackoffMs);
+                console.warn(JSON.stringify({
+                    event: 'sync_delegated_push_retry',
+                    attempt,
+                    maxAttempts: delegateMaxAttempts,
+                    status: response?.status ?? null,
+                    delayMs,
+                    error: response ? null : errorMessage(lastError),
+                }));
+                await scheduler.wait(delayMs);
+            }
+            throw lastError ?? new Error('delegated push retry exhausted');
+        }
+        #log(fields) {
+            console.log(JSON.stringify({
+                event: 'sync_request',
+                hostVersion: config.hostVersion,
+                engineVersion: engine_version(),
+                ...fields,
+            }));
+        }
+        #enqueueWake(originClientID) {
+            this.#wakeOrigins.add(originClientID);
+            for (const socket of this.ctx.getWebSockets()) {
+                const attachment = socketAttachment(socket);
+                if (!attachment ||
+                    attachment.clientID === originClientID ||
+                    this.#pulling.has(attachment.clientID)) {
+                    continue;
+                }
+                this.#wakeRecipients.add(socket);
+            }
+            return this.#scheduleWake();
+        }
+        #scheduleWake() {
+            if (!this.#wakePromise) {
+                const queuedAt = performance.now();
+                this.#wakePromise = (async () => {
+                    await scheduler.wait(wakeCoalesceMs);
+                    const fanoutStarted = performance.now();
+                    const origins = this.#wakeOrigins;
+                    this.#wakeOrigins = new Set();
+                    const recipients = this.#wakeRecipients;
+                    this.#wakeRecipients = new Set();
+                    this.#counters.wakeBatches++;
+                    let sent = 0;
+                    const sockets = this.ctx.getWebSockets();
+                    for (const socket of recipients) {
+                        try {
+                            socket.send('wake');
+                            sent++;
+                            this.#counters.wakeFrames++;
+                        }
+                        catch {
+                            // A closing hibernating socket disappears from getWebSockets;
+                            // a race here is advisory and carries no correctness weight.
+                        }
+                    }
+                    console.log(JSON.stringify({
+                        event: 'sync_wake',
+                        hostVersion: config.hostVersion,
+                        socketCount: sockets.length,
+                        originCount: origins.size,
+                        sent,
+                        eligibleRecipients: recipients.size,
+                        coalesceMs: fanoutStarted - queuedAt,
+                        fanoutMs: performance.now() - fanoutStarted,
+                    }));
+                })().finally(() => {
+                    this.#wakePromise = null;
+                    if (this.#wakeOrigins.size > 0)
+                        void this.#scheduleWake();
+                });
+            }
+            return this.#wakePromise;
+        }
+        async #pull(request, claims, namespace) {
+            this.#counters.pulls++;
+            this.#engineDb.resetStats();
+            const started = performance.now();
+            let transactionMs = 0;
+            let body;
+            try {
+                body = await requestObject(request);
+                const queryAware = this.#queryAwareOverride() ??
+                    (typeof config.queryAware === 'function'
+                        ? config.queryAware(claims)
+                        : (config.queryAware ?? Boolean(config.resolveQuery)));
+                const transformVersion = queryAware
+                    ? typeof config.queryTransformVersion === 'function'
+                        ? config.queryTransformVersion(claims)
+                        : (config.queryTransformVersion ?? 0)
+                    : 0;
+                if (!Number.isSafeInteger(transformVersion) || transformVersion < 0) {
+                    throw new TypeError('queryTransformVersion must be a non-negative safe integer');
+                }
+                const releaseQueryPull = queryAware && config.resolveQuery
+                    ? await this.#acquireQueryPullLock(typeof body.clientGroupID === 'string' ? body.clientGroupID : '')
+                    : null;
+                let response;
+                try {
+                    if (queryAware && body.queries) {
+                        const queries = body.queries;
+                        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;
+                                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;
+                                    let ast;
+                                    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 } };
+                        }
+                    }
+                    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));
+                            if (duringFault)
+                                throw this.#faultError(duringFault, 'pull_during_tx');
+                            return result;
+                        });
+                        transactionMs = performance.now() - txStarted;
+                    }
+                    finally {
+                        this.#pulling.delete(clientID);
+                    }
+                }
+                finally {
+                    releaseQueryPull?.();
+                }
+                const afterPullFault = this.#takeFault('pull_after_commit');
+                if (afterPullFault)
+                    throw this.#faultError(afterPullFault, 'pull_after_commit');
+                const patch = Array.isArray(response.rowsPatch) ? response.rowsPatch : [];
+                const queriesBody = body.queries;
+                const queryPuts = queryAware && Array.isArray(queriesBody?.patch)
+                    ? queriesBody.patch.filter((entry) => entry?.op === 'put').length
+                    : 0;
+                this.#counters.queryRecompilations += queryPuts;
+                const state = this.#engineStateBestEffort();
+                this.#log({
+                    namespaceHash: namespace,
+                    requestKind: 'pull',
+                    resultClass: response.unchanged === true ? 'unchanged' : 'success',
+                    inputCookie: body.cookie ?? null,
+                    outputCookie: response.cookie ?? null,
+                    retainedFloor: state?.floor ?? null,
+                    currentWatermark: state?.watermark ?? null,
+                    changeRowsScanned: null,
+                    changeRowsIncluded: null,
+                    queriesRecomputed: queryPuts,
+                    rowPuts: patch.filter((entry) => entry?.op === 'put').length,
+                    rowDeletes: patch.filter((entry) => entry?.op === 'del').length,
+                    lmidAdvances: 0,
+                    transactionMs,
+                    totalMs: performance.now() - started,
+                    resetReason: null,
+                    wasmBoundaryCalls: this.#counters.wasmBoundaryCalls,
+                    sql: this.#engineDb.stats,
+                });
+                return json(response);
+            }
+            catch (error) {
+                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: state?.floor ?? null,
+                    currentWatermark: state?.watermark ?? null,
+                    changeRowsScanned: null,
+                    changeRowsIncluded: 0,
+                    queriesRecomputed: 0,
+                    rowPuts: 0,
+                    rowDeletes: 0,
+                    lmidAdvances: 0,
+                    transactionMs,
+                    totalMs: performance.now() - started,
+                    resetReason: status === 409 ? errorMessage(error) : null,
+                });
+                return json({ error: errorMessage(error) }, status);
+            }
+        }
+        async #push(request, claims, namespace, upstreamPath) {
+            this.#counters.pushes++;
+            this.#engineDb.resetStats();
+            const started = performance.now();
+            let transactionMs = 0;
+            let lmidAdvances = 0;
+            let resultClass = 'success';
+            if (!this.#writerEnabled()) {
+                // 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.#engineStateBestEffort();
+                this.#log({
+                    namespaceHash: namespace,
+                    requestKind: 'push',
+                    resultClass: 'writer_disabled',
+                    inputCookie: null,
+                    outputCookie: null,
+                    retainedFloor: state?.floor ?? null,
+                    currentWatermark: state?.watermark ?? null,
+                    changeRowsScanned: 0,
+                    changeRowsIncluded: 0,
+                    queriesRecomputed: 0,
+                    rowPuts: 0,
+                    rowDeletes: 0,
+                    lmidAdvances: 0,
+                    transactionMs: 0,
+                    totalMs: performance.now() - started,
+                    resetReason: 'writer disabled by operator',
+                    wasmBoundaryCalls: this.#counters.wasmBoundaryCalls,
+                    sql: this.#engineDb.stats,
+                });
+                return json({ error: 'writer disabled by operator' }, 503);
+            }
+            if (config.mutateUrl) {
+                try {
+                    const bytes = await request.arrayBuffer();
+                    const body = JSON.parse(new TextDecoder().decode(bytes));
+                    const plan = this.#wasm(() => engine_push_validate(body));
+                    if (plan.kind === 'respond')
+                        return json(plan.response);
+                    const endpoint = new URL(`${upstreamPath ?? ''}${config.mutateUrl}`, config.mutateOrigin ?? 'https://upstream.invalid');
+                    const headers = new Headers(request.headers);
+                    headers.delete(CLAIMS_HEADER);
+                    headers.delete(NAMESPACE_HEADER);
+                    headers.delete(UPSTREAM_PATH_HEADER);
+                    headers.set('host', endpoint.host);
+                    const upstreamResponse = await this.#fetchDelegatedPush(endpoint, headers, bytes, this.#engineState().upstreamWatermark === '0');
+                    if (!upstreamResponse.ok) {
+                        return new Response(upstreamResponse.body, upstreamResponse);
+                    }
+                    const upstreamBody = (await upstreamResponse.json());
+                    const delegatedResponse = upstreamBody.pushResponse ?? upstreamBody;
+                    if (isStructuredPushFailed(delegatedResponse)) {
+                        // PushFailed is a successful protocol response describing an
+                        // application-level failure. There are intentionally no mutation
+                        // acknowledgements to finalize in the host; preserve the body so
+                        // the Zero client can apply its retry/error policy.
+                        return json({ pushResponse: delegatedResponse });
+                    }
+                    const acknowledged = typeof upstreamBody.pushResponse === 'object' &&
+                        upstreamBody.pushResponse !== null &&
+                        'mutations' in upstreamBody.pushResponse
+                        ? upstreamBody.pushResponse.mutations
+                        : upstreamBody.mutations;
+                    if (!Array.isArray(acknowledged)) {
+                        throw new Error('delegated push returned no mutation results');
+                    }
+                    for (const mutation of plan.mutations) {
+                        const ack = acknowledged.some((result) => result.id?.clientID === mutation.clientID &&
+                            String(result.id?.id) === mutation.id);
+                        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(this.#engineDb, plan.clientGroupID, mutation.clientID, mutation.id, claims.userID));
+                            if (decision.kind === 'applied') {
+                                this.#wasm(() => engine_finalize(this.#engineDb, plan.clientGroupID, mutation.clientID, mutation.id));
+                                lmidAdvances++;
+                            }
+                        });
+                    }
+                    if (lmidAdvances > 0) {
+                        this.ctx.storage.transactionSync(() => this.#wasm(() => engine_prune(this.#engineDb, this.#retainChanges())));
+                    }
+                    return json({ pushResponse: delegatedResponse });
+                }
+                catch (error) {
+                    const status = statusOf(error);
+                    return json(errorBody(error), status);
+                }
+            }
+            try {
+                const body = await requestObject(request);
+                const beforeMutationFault = this.#takeFault('push_before_mutation');
+                if (beforeMutationFault)
+                    throw this.#faultError(beforeMutationFault, 'push_before_mutation');
+                const plan = this.#wasm(() => engine_push_validate(body));
+                if (plan.kind === 'respond')
+                    return json(plan.response);
+                const results = [];
+                for (const mutation of plan.mutations) {
+                    const deferred = createPostCommitEffects();
+                    try {
+                        const txStarted = performance.now();
+                        // consume the before-commit fault OUTSIDE the transaction it is
+                        // about to abort: taken inside, the control-table delete rolls
+                        // back with the abort and the fault re-fires on every retry
+                        // instead of being one-shot.
+                        const beforeCommitFault = this.#takeFault('push_after_write_before_commit');
+                        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.beginAttempt();
+                            const decision = this.#wasm(() => engine_preflight(this.#engineDb, plan.clientGroupID, mutation.clientID, mutation.id, claims.userID));
+                            if (decision.kind === 'replay')
+                                return decision;
+                            const mutator = config.mutators?.[mutation.name];
+                            if (!mutator)
+                                throw new Error(`unknown mutator: ${mutation.name}`);
+                            await mutator(this.#mutatorSql, mutation.args[0] ?? null, {
+                                claims,
+                                clientID: mutation.clientID,
+                                mutationID: mutation.id,
+                                defer: deferred.defer,
+                            });
+                            if (beforeCommitFault)
+                                throw this.#faultError(beforeCommitFault, 'push_after_write_before_commit');
+                            this.#wasm(() => engine_finalize(this.#engineDb, plan.clientGroupID, mutation.clientID, mutation.id));
+                            return decision;
+                        });
+                        transactionMs += performance.now() - txStarted;
+                        if (preflight.kind === 'replay') {
+                            const expected = preflight
+                                .expected;
+                            results.push({
+                                clientID: mutation.clientID,
+                                id: mutation.id,
+                                result: {
+                                    error: 'alreadyProcessed',
+                                    details: `Ignoring mutation from ${mutation.clientID} with ID ${mutation.id} as it was already processed. Expected: ${expected}`,
+                                },
+                            });
+                            continue;
+                        }
+                        lmidAdvances++;
+                        results.push({
+                            clientID: mutation.clientID,
+                            id: mutation.id,
+                            result: {},
+                        });
+                        // Keep the advisory fan-out off the push response's critical path.
+                        // 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 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 = isMutationApplicationError(error);
+                        if (!isAppError)
+                            throw error;
+                        this.#counters.applicationErrors++;
+                        resultClass = 'application_error';
+                        const appError = error;
+                        const txStarted = performance.now();
+                        await this.ctx.storage.transaction(async () => {
+                            this.#wasm(() => engine_record_app_error(this.#engineDb, plan.clientGroupID, mutation.clientID, mutation.id, claims.userID));
+                        });
+                        transactionMs += performance.now() - txStarted;
+                        lmidAdvances++;
+                        results.push({
+                            clientID: mutation.clientID,
+                            id: mutation.id,
+                            result: {
+                                error: 'app',
+                                message: appError.message,
+                                details: appError.details ?? appError.message,
+                            },
+                        });
+                        this.ctx.waitUntil(this.#enqueueWake(mutation.clientID));
+                    }
+                }
+                if (plan.mutations.length > 0) {
+                    const txStarted = performance.now();
+                    await this.ctx.storage.transaction(async () => {
+                        this.#wasm(() => engine_prune(this.#engineDb, this.#retainChanges()));
+                    });
+                    transactionMs += performance.now() - txStarted;
+                    this.#counters.retentionRuns++;
+                }
+                const afterCommitFault = this.#takeFault('push_after_commit_before_response');
+                if (afterCommitFault)
+                    throw this.#faultError(afterCommitFault, 'push_after_commit_before_response');
+                const response = this.#wasm(() => engine_assemble_push_response(results));
+                const state = this.#engineStateBestEffort();
+                this.#log({
+                    namespaceHash: namespace,
+                    requestKind: 'push',
+                    resultClass,
+                    inputCookie: null,
+                    outputCookie: null,
+                    retainedFloor: state?.floor ?? null,
+                    currentWatermark: state?.watermark ?? null,
+                    changeRowsScanned: 0,
+                    changeRowsIncluded: 0,
+                    queriesRecomputed: 0,
+                    rowPuts: 0,
+                    rowDeletes: 0,
+                    lmidAdvances,
+                    transactionMs,
+                    totalMs: performance.now() - started,
+                    resetReason: null,
+                    wasmBoundaryCalls: this.#counters.wasmBoundaryCalls,
+                    sql: this.#engineDb.stats,
+                });
+                if (this.#dropNextPushResponse) {
+                    this.#dropNextPushResponse = false;
+                    return json({ error: 'intentionally dropped push response' }, 503);
+                }
+                return json(response);
+            }
+            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: state?.floor ?? null,
+                    currentWatermark: state?.watermark ?? null,
+                    changeRowsScanned: 0,
+                    changeRowsIncluded: 0,
+                    queriesRecomputed: 0,
+                    rowPuts: 0,
+                    rowDeletes: 0,
+                    lmidAdvances,
+                    transactionMs,
+                    totalMs: performance.now() - started,
+                    resetReason: null,
+                });
+                return json({ error: errorMessage(error) }, status);
+            }
+        }
+        #wake(request) {
+            if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
+                return json({ error: 'websocket upgrade required' }, 426);
+            }
+            const clientID = new URL(request.url).searchParams.get('clientID');
+            if (!clientID)
+                return json({ error: 'clientID is required' }, 400);
+            const pair = new WebSocketPair();
+            const [client, server] = Object.values(pair);
+            server.serializeAttachment({ clientID });
+            this.ctx.acceptWebSocket(server, [`client:${clientID}`]);
+            // The alarm is only a safety net for an actively connected consumer.
+            // A namespace with no wake socket has nobody to notify; its next pull or
+            // push ingests synchronously. Arming from construction made every
+            // namespace poll upstream forever after its first request, even across
+            // DO eviction, producing a permanent rows-written floor at zero traffic.
+            this.#armUpstreamAlarm();
+            return new Response(null, { status: 101, webSocket: client });
+        }
+        #admin(route, request, upstreamPath) {
+            if (route === '/admin/health')
+                return json({ ok: true });
+            if (route === '/admin/upstream-write-budget' && request.method === 'GET')
+                return this.#upstreamWriteBudgetStatus();
+            if (route === '/admin/status') {
+                const heap = performance.memory;
+                return this.ctx.storage.getAlarm().then((upstreamAlarmAt) => json({
+                    bootID: this.#bootID,
+                    idleTeardownMs,
+                    hibernations: this.#hibernations,
+                    databaseSizeBytes: this.ctx.storage.sql.databaseSize,
+                    connectedWakeSockets: this.ctx.getWebSockets().length,
+                    upstreamAlarmAt,
+                    writerEnabled: this.#writerEnabled(),
+                    wasmMemoryBytes: engine_memory_bytes(),
+                    heapUsedBytes: heap?.usedJSHeapSize ?? null,
+                    heapTotalBytes: heap?.totalJSHeapSize ?? null,
+                    heapLimitBytes: heap?.jsHeapSizeLimit ?? null,
+                    engine: this.#engineStateBestEffort(),
+                    counters: this.#counters,
+                    ingestBreaker: this.#ingestBreaker.status(),
+                }));
+            }
+            if (route === '/admin/sql') {
+                return request.json().then((body) => {
+                    const { params, query } = body;
+                    if (typeof query !== 'string')
+                        return json({ error: 'query is required' }, 400);
+                    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') {
+                this.ctx.storage.transactionSync(() => this.#wasm(() => engine_invalidate(this.#engineDb)));
+                return json({ ok: true, engine: this.#engineState() });
+            }
+            if (route === '/admin/resnapshot') {
+                if (request.method !== 'POST') {
+                    return json({ error: 'method not allowed' }, 405);
+                }
+                return (async () => {
+                    try {
+                        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,
+                            engine,
+                        });
+                    }
+                    catch (error) {
+                        return json(errorBody(error), statusOf(error));
+                    }
+                })();
+            }
+            if (route === '/admin/drop-next-push-response') {
+                this.#dropNextPushResponse = true;
+                return json({ ok: true });
+            }
+            if (route === '/admin/restart') {
+                this.ctx.abort('admin requested durable object restart');
+                return json({ ok: true, bootID: this.#bootID });
+            }
+            if (route === '/admin/visibility') {
+                return request.json().then((body) => {
+                    const enabled = Boolean(body.enabled);
+                    this.#controlSet('visibilityEnabled', enabled ? '1' : '0');
+                    return json({ ok: true, enabled });
+                });
+            }
+            if (route === '/admin/query-aware') {
+                return request.json().then((body) => {
+                    const enabled = Boolean(body.enabled);
+                    this.#controlSet('queryAwareOverride', enabled ? '1' : '0');
+                    return json({ ok: true, enabled });
+                });
+            }
+            if (route === '/admin/retention') {
+                return request
+                    .json()
+                    .catch(() => ({}))
+                    .then((body) => {
+                    const value = Number(body.retainChanges);
+                    if (!Number.isSafeInteger(value) || value < 0)
+                        return json({ error: 'invalid retainChanges' }, 400);
+                    this.#controlSet('retainChanges', String(value));
+                    return json({ ok: true, retainChanges: value });
+                });
+            }
+            if (route === '/admin/writer') {
+                if (request.method === 'GET')
+                    return json({ writerEnabled: this.#writerEnabled() });
+                return request
+                    .json()
+                    .catch(() => ({}))
+                    .then((body) => {
+                    const enabled = body.enabled;
+                    if (typeof enabled !== 'boolean')
+                        return json({ error: 'enabled must be a boolean' }, 400);
+                    this.#controlSet('writerEnabled', enabled ? '1' : '0');
+                    return json({ ok: true, writerEnabled: enabled });
+                });
+            }
+            if (route === '/admin/ingest-breaker') {
+                if (request.method === 'GET')
+                    return json(this.#ingestBreaker.status());
+                this.#ingestBreaker.reopen();
+                this.#controlDelete('ingestBreakerReason', 'ingestBreakerRetryAt', 'ingestBreakerTrips');
+                console.log(JSON.stringify({ event: 'sync_upstream_ingest_breaker_reopened' }));
+                return json({ ok: true, ...this.#ingestBreaker.status() });
+            }
+            if (route === '/admin/fault') {
+                return request
+                    .json()
+                    .catch(() => ({}))
+                    .then((body) => {
+                    const value = body;
+                    if (value.clear === true) {
+                        this.#directSql.exec("DELETE FROM _zsync_host_control WHERE key IN ('faultPoint', 'faultKind')");
+                        return json({ ok: true, armed: null });
+                    }
+                    const points = [
+                        'push_before_mutation',
+                        'push_after_write_before_commit',
+                        'push_after_commit_before_response',
+                        'pull_during_tx',
+                        'pull_after_commit',
+                    ];
+                    if (!points.includes(value.point))
+                        return json({ error: 'invalid fault point' }, 400);
+                    if (value.kind !== 'error' && value.kind !== 'quota')
+                        return json({ error: 'invalid fault kind' }, 400);
+                    this.#controlSet('faultPoint', value.point);
+                    this.#controlSet('faultKind', value.kind);
+                    return json({
+                        ok: true,
+                        armed: { point: value.point, kind: value.kind },
+                    });
+                });
+            }
+            return json({ error: 'not found' }, 404);
+        }
+        async fetch(request) {
+            this.#simulateIdleTeardown(Date.now());
+            const route = routeAfterNamespace(new URL(request.url).pathname);
+            const namespace = request.headers.get(NAMESPACE_HEADER) ?? 'unknown';
+            const upstreamPath = this.#rememberUpstreamPath(request);
+            if (route.startsWith('/admin/'))
+                return this.#admin(route, request, upstreamPath);
+            if (route === '/wake' && request.method === 'GET')
+                return this.#wake(request);
+            if (route === '/notify' && request.method === 'POST') {
+                try {
+                    const applied = await this.#ingest(upstreamPath);
+                    return json({ ok: true, applied });
+                }
+                catch (error) {
+                    return json(errorBody(error), statusOf(error));
+                }
+            }
+            const claims = claimsFromRequest(request);
+            if (!claims)
+                return json({ error: 'missing normalized claims' }, 401);
+            if (route === '/pull' && request.method === 'POST') {
+                try {
+                    await this.#ingest(upstreamPath);
+                }
+                catch (error) {
+                    // Workerd requires a forwarded request body to be consumed even when
+                    // ingest fails before the pull handler parses it.
+                    await request.arrayBuffer();
+                    return json(errorBody(error), statusOf(error));
+                }
+                return this.#pull(request, claims, namespace);
+            }
+            if (route === '/push' && request.method === 'POST') {
+                // A push may be the first request for a fresh namespace. DATA's
+                // /changes call is also its schema-provisioning barrier, so complete it
+                // before delegating the mutation to APP. Pull already enforces this
+                // ordering above; skipping it here let APP race half-created tables and
+                // surface a terminal, bodyless 500 to Zero.
+                try {
+                    await this.#ingest(upstreamPath);
+                }
+                catch (error) {
+                    await request.arrayBuffer();
+                    return json(errorBody(error), statusOf(error));
+                }
+                return this.#push(request, claims, namespace, upstreamPath);
+            }
+            return json({ error: 'not found' }, 404);
+        }
+        async alarm() {
+            if (this.ctx.getWebSockets().length === 0)
+                return;
+            try {
+                await this.#ingest();
+            }
+            catch (error) {
+                console.error(JSON.stringify({
+                    event: 'sync_upstream_ingest_error',
+                    status: statusOf(error),
+                    error: errorMessage(error),
+                }));
+            }
+            finally {
+                if (this.ctx.getWebSockets().length > 0) {
+                    const retryAfterMs = this.#ingestBreaker.status().retryAfterMs;
+                    await this.ctx.storage.setAlarm(Date.now() + Math.max(upstreamIntervalMs, retryAfterMs));
+                }
+            }
+        }
+        webSocketMessage(socket, message) {
+            if (message === 'ping')
+                socket.send('pong');
+        }
+        webSocketClose(socket, code, reason, _wasClean) {
+            // The peer already closed, so echo the close to release the socket — but
+            // WebSocket.close() rejects reserved/absent codes (1005 "no status", 1006
+            // abnormal, 1015) with InvalidAccessError, and a real browser routinely
+            // closes with 1001/1005. An uncaught throw here aborts the DO, so only
+            // echo an application-permitted code and otherwise close cleanly.
+            const echoable = code === 1000 || (code >= 3000 && code <= 4999);
+            socketCloseQuietly(socket, echoable ? code : 1000, echoable ? reason : '');
+        }
+        webSocketError(socket, _error) {
+            socketCloseQuietly(socket, 1011, 'wake socket error');
+        }
+    };
+}