orez-sync-cf-host 0.5.17 → 0.5.19

package/README.md

@@ -17,16 +17,99 @@ 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>` upgrades to a Durable Object hibernating
-WebSocket. Socket attachments carry only the client ID. A committed push sends a
-text `wake` frame to all connected clients except the pusher; a scheduler window
+`GET /<namespace>/wake?clientID=<id>&wakeToken=<capability>` upgrades to a
+Durable Object hibernating WebSocket after `authorizeWake` accepts the
+capability. Browser consumers should mint a short-lived, namespace-scoped token
+at their authenticated edge because the native WebSocket constructor cannot set
+an authorization header. Socket attachments carry only the client ID. A
+committed push sends a text `wake` frame to all connected clients except the
+pusher; a scheduler window
 coalesces a burst into one frame per socket. `ping` receives `pong`. The message
 contains no state and carries no correctness weight: clients pull after a wake
 and retain their safety poll. `ctx.getWebSockets()` plus serialized attachments
 means sockets remain discoverable after hibernation/re-instantiation.
 
+### Consumer-minted wake capabilities
+
+The consumer Worker owns both token minting and verification. Add an
+authenticated edge route that signs the namespace and a short expiry, typically
+30 to 60 seconds, with a secret that never reaches the browser. Return only the
+signed token:
+
+```ts
+// consumer edge route, after normal session authentication
+const expiresAt = Date.now() + 60_000
+const token = await signWakeToken({ namespace, userID, expiresAt }, env.WAKE_SECRET)
+return Response.json({ token, expiresAt })
+```
+
+Pass a mint callback to the canonical HTTP transport. It calls `getToken()` for
+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,
+  wake: {
+    async getToken() {
+      const response = await fetch(`/api/sync/${namespace}/wake-token`, {
+        method: 'POST',
+      })
+      if (!response.ok) throw new Error('wake token mint failed')
+      return (await response.json()).token
+    },
+  },
+})
+```
+
+The transport appends that value as `wakeToken` because browser WebSockets
+cannot set an authorization header. Verify its signature, expiry, and namespace
+inside the consumer's `authorizeWake` callback. `sync-cf-host` deliberately does
+not prescribe a token format or hold the signing key:
+
+```ts
+authorizeWake(request, env) {
+  const url = new URL(request.url)
+  return verifyWakeToken(url.searchParams.get('wakeToken'), {
+    namespace: namespaceFrom(url),
+    secret: env.WAKE_SECRET,
+  })
+}
+```
+
+Treat the URL token as a narrowly scoped capability and avoid logging it. If
+minting or wake authorization is unavailable, the wake channel retries in the
+background while HTTP pulls and the safety poll continue to provide
+convergence.
+
 `/admin/status` reports a boot ID, hibernation simulation count, connected wake
 sockets, durable database size, engine watermark/floor, and aggregate counters.
 After the configured idle gap (5 seconds in the harness deployment), the local
@@ -42,6 +125,29 @@ callback succeeds or the request presents the deployment's `ADMIN_KEY` through
 includes the persisted writer-enabled state and wasm linear-memory byte length
 in addition to the engine/counter fields above.
 
+`POST /<namespace>/notify` is rejected unless `authorizeNotify` accepts a
+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
@@ -56,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
 
@@ -149,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.17",
+  "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

@@ -10,6 +10,12 @@ export function validatePullCaps(caps: PullCaps): PullCaps {
 export function validateSyncHostConfig<Env extends SyncHostEnv>(
   config: SyncHostConfig<Env>
 ): SyncHostConfig<Env> {
+  if (typeof config.authorizeWake !== 'function') {
+    throw new TypeError('sync host config authorizeWake is required')
+  }
+  if (typeof config.authorizeNotify !== 'function') {
+    throw new TypeError('sync host config authorizeNotify is required')
+  }
   const hasMutators = config.mutators !== undefined
   const hasDelegate = config.mutateUrl !== undefined
   if (hasMutators === hasDelegate) {
@@ -21,6 +27,9 @@ export function validateSyncHostConfig<Env extends SyncHostEnv>(
   if (config.mutateBinding !== undefined && !hasDelegate) {
     throw new TypeError('sync host config mutateBinding requires mutateUrl')
   }
+  if (config.mutateOrigin !== undefined && !hasDelegate) {
+    throw new TypeError('sync host config mutateOrigin requires mutateUrl')
+  }
   if (config.delegatedPushRetry !== undefined && !hasDelegate) {
     throw new TypeError('sync host config delegatedPushRetry requires mutateUrl')
   }
@@ -35,6 +44,20 @@ export function validateSyncHostConfig<Env extends SyncHostEnv>(
   if (config.mutateUrl && !config.mutateUrl.startsWith('/')) {
     throw new TypeError('mutateUrl must be an absolute path')
   }
+  if (config.mutateOrigin !== undefined) {
+    let origin: URL
+    try {
+      origin = new URL(config.mutateOrigin)
+    } catch {
+      throw new TypeError('mutateOrigin must be an absolute http(s) origin')
+    }
+    if (
+      (origin.protocol !== 'http:' && origin.protocol !== 'https:') ||
+      origin.origin !== config.mutateOrigin
+    ) {
+      throw new TypeError('mutateOrigin must be an absolute http(s) origin')
+    }
+  }
   if (config.upstream) {
     if (!config.upstream.binding) throw new TypeError('upstream.binding is required')
     const limit = config.upstream.changeLimit ?? 1_000
@@ -66,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

@@ -1,6 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * Apply one ordered catch-up page to staging without touching the live table
+ * namespace or live upstream watermark.
+ */
+export function engine_apply_snapshot_changes(db: any, schema: any, generation: string, batch: any): any;
+
+/**
+ * Apply one bounded source page to staging and commit its opaque cursor with
+ * the rows. The host owns one transaction per call.
+ */
+export function engine_apply_snapshot_page(db: any, schema: any, generation: string, table: string, rows: any, next_cursor?: string | null): any;
+
 /**
  * Apply one ordered page from the upstream ZeroSqlDO change feed. The host
  * owns one transaction around this call; application triggers append the
@@ -15,14 +27,26 @@ export function engine_apply_upstream_snapshot(db: any, schema: any, snapshot: a
 
 export function engine_assemble_push_response(results: any): any;
 
+/**
+ * Create a new staged generation. `start_watermark` is captured by the host
+ * from the first source snapshot-page response. The host owns the transaction.
+ */
+export function engine_begin_snapshot_generation(db: any, schema: any, start_watermark: string): any;
+
 /**
  * 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;
 
+/**
+ * Atomically rename a drained staged generation into the live namespace,
+ * invalidate pre-cutover client cookies, and advance the live source cursor.
+ */
+export function engine_finalize_snapshot_generation(db: any, schema: any, generation: string, watermark: string): any;
+
 /**
  * Production pull entry. The TypeScript host owns `transactionSync`.
  */
@@ -63,6 +87,12 @@ export function engine_prune(db: any, retain_changes: string): void;
  */
 export function engine_push_validate(body: any): any;
 
+/**
+ * Strictly read resumable snapshot progress. Storage and row-shape failures
+ * are errors; only a successful query with no active row returns null.
+ */
+export function engine_read_snapshot_progress(db: any): any;
+
 export function engine_record_app_error(db: any, client_group_id: string, client_id: string, mutation_id: string, user_id: string): void;
 
 export function engine_state(db: any): any;
@@ -73,11 +103,15 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly engine_apply_snapshot_changes: (a: any, b: any, c: number, d: number, e: any) => [number, number, number];
+    readonly engine_apply_snapshot_page: (a: any, b: any, c: number, d: number, e: number, f: number, g: any, h: number, i: number) => [number, number, number];
     readonly engine_apply_upstream: (a: any, b: any, c: any) => [number, number, number];
     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_compile_query: (a: any, b: 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, 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];
     readonly engine_handle_query_pull: (a: any, b: any, c: number, d: number, e: any, f: number, g: number) => [number, number, number];
     readonly engine_init_query_schema: (a: any) => [number, number];
@@ -87,6 +121,7 @@ export interface InitOutput {
     readonly engine_preflight: (a: any, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number, number];
     readonly engine_prune: (a: any, b: number, c: number) => [number, number];
     readonly engine_push_validate: (a: any) => [number, number, number];
+    readonly engine_read_snapshot_progress: (a: any) => [number, number, number];
     readonly engine_record_app_error: (a: any, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number];
     readonly engine_state: (a: any) => [number, number, number];
     readonly engine_version: () => [number, number];

package/src/generated/sync_wasm.js

@@ -1,5 +1,49 @@
 /* @ts-self-types="./sync_wasm.d.ts" */
 
+/**
+ * Apply one ordered catch-up page to staging without touching the live table
+ * namespace or live upstream watermark.
+ * @param {any} db
+ * @param {any} schema
+ * @param {string} generation
+ * @param {any} batch
+ * @returns {any}
+ */
+export function engine_apply_snapshot_changes(db, schema, generation, batch) {
+    const ptr0 = passStringToWasm0(generation, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.engine_apply_snapshot_changes(db, schema, ptr0, len0, batch);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Apply one bounded source page to staging and commit its opaque cursor with
+ * the rows. The host owns one transaction per call.
+ * @param {any} db
+ * @param {any} schema
+ * @param {string} generation
+ * @param {string} table
+ * @param {any} rows
+ * @param {string | null} [next_cursor]
+ * @returns {any}
+ */
+export function engine_apply_snapshot_page(db, schema, generation, table, rows, next_cursor) {
+    const ptr0 = passStringToWasm0(generation, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(table, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    var ptr2 = isLikeNone(next_cursor) ? 0 : passStringToWasm0(next_cursor, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len2 = WASM_VECTOR_LEN;
+    const ret = wasm.engine_apply_snapshot_page(db, schema, ptr0, len0, ptr1, len1, rows, ptr2, len2);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Apply one ordered page from the upstream ZeroSqlDO change feed. The host
  * owns one transaction around this call; application triggers append the
@@ -44,15 +88,34 @@ export function engine_assemble_push_response(results) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Create a new staged generation. `start_watermark` is captured by the host
+ * from the first source snapshot-page response. The host owns the transaction.
+ * @param {any} db
+ * @param {any} schema
+ * @param {string} start_watermark
+ * @returns {any}
+ */
+export function engine_begin_snapshot_generation(db, schema, start_watermark) {
+    const ptr0 = passStringToWasm0(start_watermark, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.engine_begin_snapshot_generation(db, schema, ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Compile a validated Zero query AST for a consumer mutator's transactional
  * `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]);
     }
@@ -78,6 +141,27 @@ export function engine_finalize(db, client_group_id, client_id, mutation_id) {
     }
 }
 
+/**
+ * Atomically rename a drained staged generation into the live namespace,
+ * invalidate pre-cutover client cookies, and advance the live source cursor.
+ * @param {any} db
+ * @param {any} schema
+ * @param {string} generation
+ * @param {string} watermark
+ * @returns {any}
+ */
+export function engine_finalize_snapshot_generation(db, schema, generation, watermark) {
+    const ptr0 = passStringToWasm0(generation, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(watermark, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.engine_finalize_snapshot_generation(db, schema, ptr0, len0, ptr1, len1);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Production pull entry. The TypeScript host owns `transactionSync`.
  * @param {any} db
@@ -221,6 +305,20 @@ export function engine_push_validate(body) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Strictly read resumable snapshot progress. Storage and row-shape failures
+ * are errors; only a successful query with no active row returns null.
+ * @param {any} db
+ * @returns {any}
+ */
+export function engine_read_snapshot_progress(db) {
+    const ret = wasm.engine_read_snapshot_progress(db);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * @param {any} db
  * @param {string} client_group_id

package/src/harness-config.ts

@@ -329,6 +329,93 @@ const harnessMutators = registerMutators({
   },
 })
 
+const WAKE_TOKEN_TTL_MS = 60_000
+
+type HarnessWakeTokenPayload = {
+  namespace: string
+  userID: string
+  expiresAt: number
+}
+
+export async function mintHarnessWakeToken(
+  namespace: string,
+  userID: string,
+  secret: string
+): Promise<{ token: string; expiresAt: number }> {
+  const expiresAt = Date.now() + WAKE_TOKEN_TTL_MS
+  const payload = encodeBase64URL(
+    new TextEncoder().encode(JSON.stringify({ namespace, userID, expiresAt }))
+  )
+  return {
+    token: `${payload}.${await signWakeToken(payload, secret)}`,
+    expiresAt,
+  }
+}
+
+async function verifyHarnessWakeToken(
+  token: string,
+  namespace: string,
+  secret: string
+): Promise<boolean> {
+  try {
+    const [payload, signature, extra] = token.split('.')
+    if (!payload || !signature || extra) return false
+    const key = await wakeTokenKey(secret, ['verify'])
+    const valid = await crypto.subtle.verify(
+      'HMAC',
+      key,
+      decodeBase64URL(signature),
+      new TextEncoder().encode(payload)
+    )
+    if (!valid) return false
+    const claims = JSON.parse(
+      new TextDecoder().decode(decodeBase64URL(payload))
+    ) as HarnessWakeTokenPayload
+    return (
+      claims.namespace === namespace &&
+      typeof claims.userID === 'string' &&
+      claims.userID.length > 0 &&
+      Number.isFinite(claims.expiresAt) &&
+      claims.expiresAt > Date.now()
+    )
+  } catch {
+    return false
+  }
+}
+
+async function signWakeToken(payload: string, secret: string): Promise<string> {
+  const key = await wakeTokenKey(secret, ['sign'])
+  const signature = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    new TextEncoder().encode(payload)
+  )
+  return encodeBase64URL(new Uint8Array(signature))
+}
+
+function wakeTokenKey(secret: string, usages: KeyUsage[]): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    usages
+  )
+}
+
+function encodeBase64URL(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '')
+}
+
+function decodeBase64URL(value: string): ArrayBuffer {
+  const base64 = value.replaceAll('-', '+').replaceAll('_', '/')
+  const binary = atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '='))
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0))
+    .buffer as ArrayBuffer
+}
+
 export function harnessConfig<Env extends SyncHostEnv>(): SyncHostConfig<Env> {
   return {
     hostVersion: '0.1.0',
@@ -336,7 +423,9 @@ export function harnessConfig<Env extends SyncHostEnv>(): SyncHostConfig<Env> {
     mutators: harnessMutators,
     queryAware: false,
     queryTransformVersion: 1,
-    resolveQuery(name, args) {
+    async resolveQuery(name, args) {
+      const delayMs = Number((args[0] as { delayMs?: unknown } | undefined)?.delayMs ?? 0)
+      if (delayMs > 0) await scheduler.wait(delayMs)
       return queryNameToAst(name, args) as never
     },
     initialize: initializeHarness,
@@ -349,6 +438,21 @@ export function harnessConfig<Env extends SyncHostEnv>(): SyncHostConfig<Env> {
         ?.match(/^Bearer token-(.+)$/)?.[1]
       return userID ? { userID } : null
     },
+    authorizeWake(request, env) {
+      const url = new URL(request.url)
+      const namespace = url.pathname.split('/')[1]
+      if (!namespace || !env.ADMIN_KEY) return false
+      return verifyHarnessWakeToken(
+        url.searchParams.get('wakeToken') ?? '',
+        namespace,
+        env.ADMIN_KEY
+      )
+    },
+    authorizeNotify(request, env) {
+      return (
+        Boolean(env.ADMIN_KEY) && request.headers.get('x-admin-key') === env.ADMIN_KEY
+      )
+    },
     visibility: {
       rowLocal: false,
       filter(table, claims) {