@syncular/server-workers 0.15.23 → 0.15.25

package/README.md

@@ -22,13 +22,11 @@ The HTTP binding (SPEC §1.1):
 | `<mount>/blobs/{id}` | PUT | Blob upload, content-address verified (§5.9.3) |
 | `<mount>/blobs/{id}` | GET | Blob download, row-derived re-auth (§5.9.5) |
 
-**Realtime (`GET <mount>/realtime`, §8) is supported** via a Durable Object —
-see "Workers realtime — the Durable Object" below. It is opt-in: pass a
-`realtime` option to `createWorkersFetchHandler` and add the DO binding to
-`wrangler.toml`. Omit it for an HTTP-only deployment — per SPEC §1.1 that is
-fully conformant: reference clients that cannot open the socket sync over
-`POST /sync`, which carries identical semantics. This is a smaller, complete
-deployment, not a degraded one — no fallback is implied.
+**Every D1 `/sync` round that may push traverses a per-partition Durable
+Object queue.** Pass `coordinator` for HTTP-only transport, or `realtime` to
+reuse the same namespace while also mounting `GET <mount>/realtime` (§8).
+WebSockets are optional; D1 write coordination is not. A plain stateless D1
+writer fails closed before app-row mutation.
 
 ## Usage
 
@@ -47,6 +45,7 @@ import { schema } from './syncular.generated'; // typegen output
 
 interface Env {
   DB: D1Database; // wrangler.toml [[d1_databases]] binding = "DB"
+  SYNC_COORDINATOR: DurableObjectNamespace<SyncularRealtimeDO>;
   R2_ACCOUNT_ID: string;
   R2_ACCESS_KEY_ID: string;
   R2_SECRET_ACCESS_KEY: string;
@@ -76,23 +75,27 @@ function syncConfig(env: Env): SyncServerConfig {
     blobSignedUrls: s3PresignedBlobUrls(blobs, { ttlSeconds: 900 }),
     resolveScopes: (args) => resolveScopes(args, env),
     // No `sqliteImageBuilder`: Workers has no SQLite engine, so bit-2
-    // clients are served the rows lane (§5.3 support floor). No `realtime`:
-    // the DO follow-up.
+    // clients are served the rows lane (§5.3 support floor).
   };
 }
 
 export default {
-  fetch: createWorkersFetchHandler<Env>((env) => ({
-    config: syncConfig(env),
-    authenticate: (request) => authenticate(request, env),
-  })),
+  fetch: createWorkersFetchHandler<Env>({
+    config: (env) => ({
+      config: syncConfig(env),
+      authenticate: (request) => authenticate(request, env),
+    }),
+    coordinator: (env) => ({ namespace: env.SYNC_COORDINATOR }),
+  }),
 };
 ```
 
 `createWorkersFetchHandler(factory)` builds the Hono app once per request from
 the factory and delegates. Building per request keeps the handler stateless
 (no module-global mutable server) — the Workers-correct posture, since each
-invocation may run on a fresh isolate.
+invocation may run on a fresh isolate. The coordinator forwards authenticated
+`/sync` bodies to the partition DO; segments and blob endpoints remain direct.
+The complete DO class and canonical config factory are shown under "Wiring".
 
 See `wrangler.toml.example` for the binding config.
 
@@ -126,26 +129,18 @@ immediately (autocommit) and **buffers** writes, flushing them as one atomic
 rolls back by never flushing). A read-your-own-writes overlay makes `getRow`
 see buffered writes of the same commit.
 
-**Concurrency posture.** The dense per-partition `commitSeq` (§2.1) is
-allocated by reading `max_commit_seq` live and buffering the `+1`. Under one
-Worker request this is exact. For two concurrent pushes to the *same
-partition*, serialize the writes: the DO realtime host (the follow-up) is the
-natural per-partition serialization point; a stateless HTTP-only deployment
-that expects concurrent same-partition writes SHOULD front D1 per-partition
-writes with a coordinating primitive (a DO or a Queue). This mirrors
-Postgres's per-partition row lock, achieved by placement rather than a lock
-D1 does not expose. Cross-partition pushes never contend.
-
-**Whole-commit validation fails closed without that coordinator.** SPEC §6.8
-must hold serialization from before candidate reads through commit. A plain
-`new D1ServerStorage(env.DB)` therefore rejects a push whenever
-`commitValidator` is configured. The storage created inside
-`SyncularRealtimeHost` opts in because that host is already one
-single-threaded DO per partition. A custom coordinated host may construct
-`new D1ServerStorage(env.DB, { commitValidationSerialized: true })`, but MUST
-never set that assertion in a stateless HTTP Worker. A realtime notifier wakes
-sockets after an HTTP commit; it does not serialize that HTTP write and is not
-sufficient for §6.8 by itself.
+**Concurrency posture.** Every push, not only whole-commit validation, must
+serialize before operation reads and re-check idempotency under that boundary.
+`createWorkersFetchHandler` forwards `/sync` to one DO per authenticated
+partition; the host uses an explicit FIFO because Durable Object events can
+interleave at `await`. Cross-partition pushes still use different DOs.
+
+A plain `new D1ServerStorage(env.DB)` fails closed before every push. Only an
+actual coordinator may construct
+`new D1ServerStorage(env.DB, { pushApplySerialized: true })`; never set that
+assertion in a stateless Worker. The deprecated
+`commitValidationSerialized` alias exists only for coordinated hosts upgrading
+from an older release and has the same every-push meaning.
 
 ## Workers realtime — the Durable Object
 
@@ -157,9 +152,10 @@ hosts the `RealtimeHub`, uses WebSocket hibernation to drive the existing
 ### Sharding: one DO per partition
 
 The DO id is `idFromName(partition)`, so **all of a partition's sockets and
-its commit fan-out live in one single-threaded DO** — which is also the
-per-partition write-serialization point the D1 storage wants (see "Concurrency
-posture"). Because the hub is the `RealtimeNotifier` (§8.2) *inside* the DO, a
+its commit fan-out live in one DO with an explicit sync-round FIFO** — which is
+also the per-partition write-serialization point the D1 storage wants (see
+"Concurrency posture"). Because the hub is the `RealtimeNotifier` (§8.2)
+*inside* the DO, a
 sync round landing over the socket fans its full delta to the partition's
 other sockets with **no LISTEN/NOTIFY** — writes and sockets are co-located.
 
@@ -198,18 +194,14 @@ So the serialized attachment is deliberately minimal — the three identity
 fields `connect` needs. Everything else is re-derived from D1, which is
 authoritative.
 
-### The wake path (HTTP push → DO)
+### HTTP sync and fanout
 
-A push landing via the *plain* HTTP handler (a stateless isolate with no
-sockets) wakes the partition's DO. Wire `durableObjectRealtimeNotifier(env.
-REALTIME)` into `SyncServerConfig.realtime`; after a commit lands it
-`stub.fetch`es the DO's internal wake path, and the DO calls `hub.wake(
-partition, 'catchup-required')` — its sockets re-pull the delta from the shared
-D1 (§8.3). This is the Workers in-platform equivalent of Postgres LISTEN/NOTIFY:
-a wake, not a byte re-broadcast, so remote sessions pay one re-pull. The wake
-is fire-and-forget — a DO fetch failure never fails the push (the commit is
-already durable; the client's next pull self-heals). A round landing *on the
-DO itself* skips this entirely: the hub fans the full delta out in-process.
+Authenticated HTTP `/sync` rounds are forwarded into the same partition DO as
+socket rounds. Applied commits therefore fan out through the in-DO hub without
+a post-commit wake race. `durableObjectRealtimeNotifier` remains available for
+an external authoritative command host that already provides equally strong
+partition serialization and needs to wake the DO after its own commit; it is
+not a substitute for the `/sync` coordinator.
 
 ### Wiring
 
@@ -220,13 +212,12 @@ DO itself* skips this entirely: the hub fans the full delta out in-process.
 // src/worker.ts
 import {
   createWorkersFetchHandler,
-  durableObjectRealtimeNotifier,
   D1ServerStorage,
   SyncularRealtimeHost,
   type RealtimeDOConfig,
 } from '@syncular/server-workers';
 import { DurableObject } from 'cloudflare:workers';
-import { MemorySegmentStore } from '@syncular/server';
+import type { RealtimeHubConfig } from '@syncular/server';
 import { schema } from './syncular.generated';
 
 interface Env {
@@ -234,14 +225,21 @@ interface Env {
   REALTIME: DurableObjectNamespace<SyncularRealtimeDO>;
 }
 
-const realtimeDOConfig = (env: Env): RealtimeDOConfig => ({
-  hubConfig: () => ({
+const canonicalSyncConfig = (
+  env: Env,
+  storage: D1ServerStorage,
+) => ({
     schema,
+    storage,
     resolveScopes: (args) => resolveScopes(args, env),
-    // §8.7: the socket carries sync rounds through the SAME handler + segment
-    // store as POST /sync — pass the same segment store the HTTP path uses.
     segments: makeSegments(env),
-  }),
+    blobs: makeBlobs(env),
+    crdtMergers: makeCrdtMergers(env),
+  } satisfies RealtimeHubConfig);
+
+const realtimeDOConfig = (env: Env): RealtimeDOConfig => ({
+  // One factory owns HTTP-forwarded and socket-round sync capabilities.
+  syncConfig: (storage) => canonicalSyncConfig(env, storage),
 });
 
 // The DO class the runtime instantiates. It delegates to SyncularRealtimeHost;
@@ -261,18 +259,14 @@ export default {
   fetch: createWorkersFetchHandler<Env>({
     config: (env) => ({
       config: {
-        schema,
-        storage: new D1ServerStorage(env.DB),
-        segments: makeSegments(env),
-        resolveScopes: (args) => resolveScopes(args, env),
-        // HTTP pushes wake the partition's DO (the LISTEN/NOTIFY analogue).
-        realtime: durableObjectRealtimeNotifier(env.REALTIME),
+        ...canonicalSyncConfig(env, new D1ServerStorage(env.DB)),
       },
       authenticate: (request) => authenticate(request, env),
     }),
     realtime: (env) => ({
       namespace: env.REALTIME,
-      // The realtime-channel auth seam (analogue of `authenticate`): resolve
+      // This namespace also coordinates authenticated HTTP /sync rounds.
+      // The realtime-channel auth seam resolves
       // the §8 upgrade identity; the `partition` selects the DO. Return
       // undefined to reject with a 401.
       authenticate: (request) => authenticateRealtime(request, env),
@@ -296,7 +290,7 @@ The hermetic tests (`test/realtime-do.test.ts`) drive the **real**
 `RealtimeSession`/`RealtimeHub`/`D1ServerStorage` code through the real DO class
 over a DO double + the D1 double + the reference codec — connect → hello →
 round-over-socket → delta-on-commit → ack, hibernation rehydration, the
-HTTP-push wake fan-out, and presence. Because the DO is a *deployment adapter*
+HTTP-forwarded push fan-out, and presence. Because the DO is a *deployment adapter*
 (same wire, same handler), that is the conformance bar.
 
 An automated `wrangler dev` smoke was **deliberately not added**: `wrangler` as

package/dist/index.d.ts

@@ -21,11 +21,9 @@
  * `SyncularRealtimeDO` (`realtime-do.ts`): one DO per partition hosting the
  * `RealtimeHub`, WebSocket hibernation driving the existing `RealtimeSession`,
  * in-DO commit fan-out, storage over the same D1 binding. Pass a
- * `realtime` option to `createWorkersFetchHandler` to mount the `/realtime`
- * upgrade route + the HTTP-push wake path; omit it for an HTTP-only
- * deployment (still fully conformant per §1.1 — clients sync over `POST
- * /sync`, identical semantics). No fallback is implied either way: HTTP-only
- * is a smaller complete deployment, not a degraded one.
+ * `realtime` option to mount `/realtime`; its namespace also coordinates D1
+ * `/sync`. An HTTP-only D1 deployment uses the `coordinator` option instead:
+ * WebSockets are optional, the per-partition push queue is not.
  */
 import { type D1Database, D1ServerStorage, type StoredCommit, type SyncServerConfig } from '@syncular/server';
 import { type SyncularHonoOptions } from '@syncular/server-hono';
@@ -59,10 +57,8 @@ export interface DurableObjectIdLike {
 }
 /**
  * Realtime wiring for `createWorkersFetchHandler`. Supplying it mounts the
- * `GET <mount>/realtime` upgrade route and the HTTP-push wake path (the
- * `RealtimeNotifier` returned by `durableObjectRealtimeNotifier`, which the
- * host spreads into its `SyncServerConfig.realtime` so a push landing in the
- * plain isolate wakes the partition's DO).
+ * `GET <mount>/realtime` upgrade route and uses the same namespace as the D1
+ * `/sync` coordinator.
  */
 export interface WorkersRealtimeOptions {
     /** The DO namespace binding (wrangler `[[durable_objects.bindings]]`). */
@@ -79,9 +75,20 @@ export interface WorkersRealtimeOptions {
 }
 /** Resolve the per-env realtime wiring for one Worker invocation. */
 export type WorkersRealtimeFactory<Env = unknown> = (env: Env, ctx: ExecutionContextLike) => WorkersRealtimeOptions | Promise<WorkersRealtimeOptions>;
+/** Per-partition Durable Object boundary for D1 sync rounds without WS. */
+export interface WorkersCoordinatorOptions {
+    readonly namespace: DurableObjectNamespaceLike;
+}
+export type WorkersCoordinatorFactory<Env = unknown> = (env: Env, ctx: ExecutionContextLike) => WorkersCoordinatorOptions | Promise<WorkersCoordinatorOptions>;
 export interface WorkersFetchHandlerOptions<Env = unknown> {
     /** Build the HTTP handler config + auth per request (see the type doc). */
     readonly config: WorkersConfigFactory<Env>;
+    /**
+     * Serialize D1 `/sync` rounds through one Durable Object per partition.
+     * Required for D1 pushes when `realtime` is omitted. If `realtime` is
+     * present its namespace is the coordinator automatically.
+     */
+    readonly coordinator?: WorkersCoordinatorFactory<Env>;
     /**
      * Realtime (§8) over a Durable Object. Omit for an HTTP-only deployment
      * (still fully conformant — clients sync over `POST /sync`).
@@ -130,6 +137,15 @@ export interface WorkersFetchHandlerOptions<Env = unknown> {
  * Workers-correct posture — each invocation may run on a fresh isolate.
  */
 export declare function createWorkersFetchHandler<Env = unknown>(factoryOrOptions: WorkersConfigFactory<Env> | WorkersFetchHandlerOptions<Env>): (request: Request, env: Env, ctx: ExecutionContextLike) => Promise<Response>;
+/**
+ * Forward an authenticated HTTP sync round to the partition's Durable Object.
+ * Pulls and pushes share this path so client-record updates and push apply use
+ * one ordered partition boundary. Other HTTP routes remain direct.
+ */
+export declare function forwardSyncRequest(request: Request, namespace: DurableObjectNamespaceLike, identity: {
+    readonly partition: string;
+    readonly actorId: string;
+}): Promise<Response>;
 /**
  * Forward a `/realtime` upgrade to the partition's DO stub. The identity is
  * carried on internal headers to the DO's upgrade endpoint (the DO trusts the
@@ -138,13 +154,14 @@ export declare function createWorkersFetchHandler<Env = unknown>(factoryOrOption
  */
 export declare function forwardRealtimeUpgrade(request: Request, namespace: DurableObjectNamespaceLike, identity: RealtimeUpgradeIdentity): Promise<Response>;
 /**
- * A `RealtimeNotifier` (§8.2) that wakes the partition's DO after a push lands
- * via the plain HTTP handler (a stateless isolate with no sockets). The DO
+ * A `RealtimeNotifier` (§8.2) for an external authoritative command host that
+ * already serializes its D1 writes and must wake the partition's DO. The DO
  * calls `hub.wake(partition, 'catchup-required')` and its sockets re-pull the
  * delta from the shared D1 (§8.3) — the Workers in-platform analogue of the
  * Postgres LISTEN/NOTIFY fan-out. A wake, not a byte re-broadcast.
  *
- * Spread this into `SyncServerConfig.realtime`. The wake is fire-and-forget:
+ * Ordinary Workers `/sync` does not need this: it already lands on the DO and
+ * fans out in-process. This wake is fire-and-forget:
  * a DO fetch failure never fails the push (the commit is already durable in
  * D1; the client's next pull or reconnect self-heals).
  */

package/dist/index.js

@@ -21,15 +21,13 @@
  * `SyncularRealtimeDO` (`realtime-do.ts`): one DO per partition hosting the
  * `RealtimeHub`, WebSocket hibernation driving the existing `RealtimeSession`,
  * in-DO commit fan-out, storage over the same D1 binding. Pass a
- * `realtime` option to `createWorkersFetchHandler` to mount the `/realtime`
- * upgrade route + the HTTP-push wake path; omit it for an HTTP-only
- * deployment (still fully conformant per §1.1 — clients sync over `POST
- * /sync`, identical semantics). No fallback is implied either way: HTTP-only
- * is a smaller complete deployment, not a degraded one.
+ * `realtime` option to mount `/realtime`; its namespace also coordinates D1
+ * `/sync`. An HTTP-only D1 deployment uses the `coordinator` option instead:
+ * WebSockets are optional, the per-partition push queue is not.
  */
-import { D1ServerStorage, } from '@syncular/server';
+import { D1ServerStorage, errorBody, SSP2_CONTENT_TYPE, SyncError, } from '@syncular/server';
 import { createSyncularHono, } from '@syncular/server-hono';
-import { REALTIME_DO_UPGRADE_PATH, REALTIME_DO_WAKE_PATH, writeIdentityHeaders, } from './realtime-do.js';
+import { REALTIME_DO_UPGRADE_PATH, REALTIME_DO_WAKE_PATH, SYNC_DO_REQUEST_PATH, writeIdentityHeaders, writeRequestIdentityHeaders, } from './realtime-do.js';
 export { D1ServerStorage } from '@syncular/server';
 export * from './realtime-do.js';
 /**
@@ -79,17 +77,52 @@ export function createWorkersFetchHandler(factoryOrOptions) {
         : factoryOrOptions;
     return async (request, env, ctx) => {
         // §8 upgrade: GET <mount>/realtime → forward to the partition's DO.
+        let realtime;
         if (options.realtime !== undefined) {
-            const realtime = await options.realtime(env, ctx);
+            realtime = await options.realtime(env, ctx);
             const upgraded = await handleRealtimeUpgrade(request, realtime);
             if (upgraded !== undefined)
                 return upgraded;
         }
         const honoOptions = await options.config(env, ctx);
+        const coordinator = options.coordinator !== undefined
+            ? await options.coordinator(env, ctx)
+            : realtime;
+        if (coordinator !== undefined && isSyncPost(request)) {
+            const auth = await honoOptions.authenticate(request);
+            if (auth === null) {
+                const error = new SyncError('sync.auth_required');
+                return Response.json(errorBody(error), { status: error.httpStatus });
+            }
+            return forwardSyncRequest(request, coordinator.namespace, auth);
+        }
         const app = createSyncularHono(honoOptions);
         return app.fetch(request);
     };
 }
+function isSyncPost(request) {
+    if (request.method !== 'POST')
+        return false;
+    const contentType = request.headers
+        .get('content-type')
+        ?.split(';')[0]
+        ?.trim();
+    if (contentType !== SSP2_CONTENT_TYPE)
+        return false;
+    const pathname = new URL(request.url).pathname;
+    return pathname === '/sync' || pathname.endsWith('/sync');
+}
+/**
+ * Forward an authenticated HTTP sync round to the partition's Durable Object.
+ * Pulls and pushes share this path so client-record updates and push apply use
+ * one ordered partition boundary. Other HTTP routes remain direct.
+ */
+export function forwardSyncRequest(request, namespace, identity) {
+    const stub = namespace.get(namespace.idFromName(identity.partition));
+    const forwarded = new Request(new URL(SYNC_DO_REQUEST_PATH, request.url), request);
+    writeRequestIdentityHeaders(forwarded.headers, identity);
+    return stub.fetch(forwarded);
+}
 /**
  * If `request` is the `GET <mount>/realtime` upgrade, authenticate it and
  * forward it to the partition's DO stub; otherwise return `undefined` so the
@@ -124,13 +157,14 @@ export function forwardRealtimeUpgrade(request, namespace, identity) {
     return stub.fetch(forwarded);
 }
 /**
- * A `RealtimeNotifier` (§8.2) that wakes the partition's DO after a push lands
- * via the plain HTTP handler (a stateless isolate with no sockets). The DO
+ * A `RealtimeNotifier` (§8.2) for an external authoritative command host that
+ * already serializes its D1 writes and must wake the partition's DO. The DO
  * calls `hub.wake(partition, 'catchup-required')` and its sockets re-pull the
  * delta from the shared D1 (§8.3) — the Workers in-platform analogue of the
  * Postgres LISTEN/NOTIFY fan-out. A wake, not a byte re-broadcast.
  *
- * Spread this into `SyncServerConfig.realtime`. The wake is fire-and-forget:
+ * Ordinary Workers `/sync` does not need this: it already lands on the DO and
+ * fans out in-process. This wake is fire-and-forget:
  * a DO fetch failure never fails the push (the commit is already durable in
  * D1; the client's next pull or reconnect self-heals).
  */

package/dist/realtime-do.d.ts

@@ -7,9 +7,9 @@
  *
  * One DO instance hosts **one `RealtimeHub`** and serves **one partition**
  * (the DO id is `idFromName(partition)`, see `realtimeStubFor`). All of a
- * partition's sockets and its commit fan-out live in that single-threaded DO —
- * which is also the per-partition write-serialization point the D1 storage
- * wants (see `d1-storage.ts` "Concurrency posture"). Because the hub is the
+ * partition's sync rounds, sockets, and commit fan-out live behind its
+ * explicit FIFO — the per-partition serialization point D1 requires. Because
+ * the hub is the
  * `RealtimeNotifier` (§8.2) *inside* the DO, a sync round that lands over the
  * socket fans its full delta out to the partition's other sockets with no
  * LISTEN/NOTIFY — writes and sockets are co-located.
@@ -60,16 +60,12 @@
  * fields `connect` needs. Everything else (`cursor`, `registrations`,
  * `lastKnownSeq`) is re-derived from D1 by `connect`, which is authoritative.
  *
- * ## The wake path (HTTP-push fan-out, the LISTEN/NOTIFY analogue)
+ * ## The wake path (external-command fan-out)
  *
- * A push landing via the *plain* Workers `fetch` handler (a stateless isolate,
- * not the DO) has applied a commit to D1 but has no in-memory sockets. It
- * wakes the partition's DO by `stub.fetch`-ing the internal `/__wake` endpoint
- * with the partition + commitSeq; the DO calls `hub.wake(partition,
- * 'catchup-required')` and its sockets re-pull the delta from the shared D1
- * (§8.3). This is the Workers in-platform equivalent of Postgres LISTEN/NOTIFY
- * — a wake, not a byte re-broadcast, so remote sessions pay one re-pull. See
- * `durableObjectRealtimeNotifier` in `index.ts` for the caller side.
+ * Ordinary HTTP `/sync` is forwarded into this DO and fans out in-process. An
+ * external authoritative command host that already provides equivalent D1
+ * partition serialization may call `/__wake` after its own commit so sockets
+ * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
  */
 import { D1ServerStorage, type RealtimeHubConfig } from '@syncular/server';
 export interface DurableObjectStateLike {
@@ -91,17 +87,24 @@ export type WebSocketPairLike = {
 /**
  * The host env a `SyncularRealtimeDO` reads. Supplied by the DO runtime via
  * the class constructor's second arg. `DB` is the D1 binding (the same one the
- * plain HTTP handler uses); `configFactory` builds the hub config from `env`.
+ * outer Worker config uses); `configFactory` builds the hub config from `env`.
  */
-export interface RealtimeDOConfig {
+export type RealtimeDOConfig = {
     /**
-     * Build the realtime hub config for this DO from its D1 storage. Mirrors the
-     * HTTP handler's config: same schema, same `resolveScopes`, same segment
-     * store (§8.7 socket rounds need it) — so a socket round and a `POST /sync`
-     * round are the SAME handler over the SAME storage.
+     * Preferred: build the complete canonical sync config around the DO's
+     * coordinated D1 storage. Reuse this factory for the outer HTTP adapter
+     * so HTTP-forwarded and socket rounds cannot drift by capability.
+     */
+    syncConfig(storage: D1ServerStorage): RealtimeHubConfig;
+    readonly hubConfig?: never;
+} | {
+    /**
+     * @deprecated Use `syncConfig`. This compatibility shape predates the
+     * canonical HTTP/realtime capability contract.
      */
     hubConfig(storage: D1ServerStorage): RealtimeHubConfigInput;
-}
+    readonly syncConfig?: never;
+};
 /**
  * The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
  * the DO from its D1 binding, so it is omitted here).
@@ -116,6 +119,7 @@ export interface RealtimeUpgradeIdentity {
 /** Internal control-request paths on the DO stub (never client-facing). */
 export declare const REALTIME_DO_WAKE_PATH = "/__syncular_realtime/wake";
 export declare const REALTIME_DO_UPGRADE_PATH = "/__syncular_realtime/upgrade";
+export declare const SYNC_DO_REQUEST_PATH = "/__syncular_realtime/sync";
 /**
  * The base `SyncularRealtimeDO`. A host subclasses (or instantiates) it with a
  * `RealtimeDOConfig`. The class is platform-shaped: `state.acceptWebSocket` +
@@ -146,7 +150,7 @@ export declare class SyncularRealtimeHost {
      * The DO `fetch` handler: routes the internal upgrade + wake control paths.
      * The Worker forwards `GET <mount>/realtime` here as an upgrade with the
      * resolved identity in headers (see `forwardRealtimeUpgrade` in `index.ts`),
-     * and forwards HTTP-push wakes to `/__syncular_realtime/wake`.
+     * and accepts external-command wakes at `/__syncular_realtime/wake`.
      */
     fetch(request: Request): Promise<Response>;
     /** Hibernation callback: an inbound frame. */
@@ -160,6 +164,10 @@ export declare class SyncularRealtimeHost {
 }
 /** Inject a `WebSocketPair` implementation (hermetic tests). */
 export declare function setWebSocketPair(impl: (new () => WebSocketPairLike) | undefined): void;
+export declare function writeRequestIdentityHeaders(headers: Headers, identity: {
+    readonly partition: string;
+    readonly actorId: string;
+}): void;
 /** Write the resolved identity onto an upgrade request's headers (Worker side). */
 export declare function writeIdentityHeaders(headers: Headers, identity: RealtimeUpgradeIdentity): void;
 /** The D1 binding, re-declared structurally (see `d1-storage.ts`). */

package/dist/realtime-do.js

@@ -7,9 +7,9 @@
  *
  * One DO instance hosts **one `RealtimeHub`** and serves **one partition**
  * (the DO id is `idFromName(partition)`, see `realtimeStubFor`). All of a
- * partition's sockets and its commit fan-out live in that single-threaded DO —
- * which is also the per-partition write-serialization point the D1 storage
- * wants (see `d1-storage.ts` "Concurrency posture"). Because the hub is the
+ * partition's sync rounds, sockets, and commit fan-out live behind its
+ * explicit FIFO — the per-partition serialization point D1 requires. Because
+ * the hub is the
  * `RealtimeNotifier` (§8.2) *inside* the DO, a sync round that lands over the
  * socket fans its full delta out to the partition's other sockets with no
  * LISTEN/NOTIFY — writes and sockets are co-located.
@@ -60,18 +60,14 @@
  * fields `connect` needs. Everything else (`cursor`, `registrations`,
  * `lastKnownSeq`) is re-derived from D1 by `connect`, which is authoritative.
  *
- * ## The wake path (HTTP-push fan-out, the LISTEN/NOTIFY analogue)
+ * ## The wake path (external-command fan-out)
  *
- * A push landing via the *plain* Workers `fetch` handler (a stateless isolate,
- * not the DO) has applied a commit to D1 but has no in-memory sockets. It
- * wakes the partition's DO by `stub.fetch`-ing the internal `/__wake` endpoint
- * with the partition + commitSeq; the DO calls `hub.wake(partition,
- * 'catchup-required')` and its sockets re-pull the delta from the shared D1
- * (§8.3). This is the Workers in-platform equivalent of Postgres LISTEN/NOTIFY
- * — a wake, not a byte re-broadcast, so remote sessions pay one re-pull. See
- * `durableObjectRealtimeNotifier` in `index.ts` for the caller side.
+ * Ordinary HTTP `/sync` is forwarded into this DO and fans out in-process. An
+ * external authoritative command host that already provides equivalent D1
+ * partition serialization may call `/__wake` after its own commit so sockets
+ * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
  */
-import { createRealtimeHub, D1ServerStorage, } from '@syncular/server';
+import { createRealtimeHub, D1ServerStorage, errorBody, handleSyncRequest, SSP2_CONTENT_TYPE, SyncError, } from '@syncular/server';
 function isAttachment(value) {
     return (typeof value === 'object' &&
         value !== null &&
@@ -82,6 +78,7 @@ function isAttachment(value) {
 /** Internal control-request paths on the DO stub (never client-facing). */
 export const REALTIME_DO_WAKE_PATH = '/__syncular_realtime/wake';
 export const REALTIME_DO_UPGRADE_PATH = '/__syncular_realtime/upgrade';
+export const SYNC_DO_REQUEST_PATH = '/__syncular_realtime/sync';
 /**
  * The base `SyncularRealtimeDO`. A host subclasses (or instantiates) it with a
  * `RealtimeDOConfig`. The class is platform-shaped: `state.acceptWebSocket` +
@@ -116,21 +113,29 @@ export class SyncularRealtimeHost {
     /** Sockets whose rehydration `hello` must be swallowed (already greeted at
      * the real upgrade — rehydration is transparent to the client). */
     #swallowHello = new Set();
+    /** Explicit FIFO: Durable Object events may interleave at `await`. */
+    #partitionTail = Promise.resolve();
     constructor(state, db, config) {
         this.#state = state;
         this.#storage = new D1ServerStorage(db, {
-            // This host is one Durable Object per partition, so the §6.8 storage
-            // precondition is true for socket rounds handled inside the object.
-            commitValidationSerialized: true,
+            // Every HTTP/socket sync round enters #serializePartition before this
+            // storage is used. One DO is selected per partition.
+            pushApplySerialized: true,
         });
         this.#config = config;
     }
     #getHub() {
         if (this.#hub === undefined) {
-            this.#hub = createRealtimeHub({
-                ...this.#config.hubConfig(this.#storage),
-                storage: this.#storage,
-            });
+            const config = this.#config.syncConfig !== undefined
+                ? this.#config.syncConfig(this.#storage)
+                : {
+                    ...this.#config.hubConfig(this.#storage),
+                    storage: this.#storage,
+                };
+            if (config.storage !== this.#storage) {
+                throw new Error('RealtimeDOConfig.syncConfig must use the coordinated storage argument');
+            }
+            this.#hub = createRealtimeHub(config);
         }
         return this.#hub;
     }
@@ -138,10 +143,13 @@ export class SyncularRealtimeHost {
      * The DO `fetch` handler: routes the internal upgrade + wake control paths.
      * The Worker forwards `GET <mount>/realtime` here as an upgrade with the
      * resolved identity in headers (see `forwardRealtimeUpgrade` in `index.ts`),
-     * and forwards HTTP-push wakes to `/__syncular_realtime/wake`.
+     * and accepts external-command wakes at `/__syncular_realtime/wake`.
      */
     async fetch(request) {
         const url = new URL(request.url);
+        if (url.pathname === SYNC_DO_REQUEST_PATH) {
+            return this.#serializePartition(() => this.#handleSync(request));
+        }
         if (url.pathname === REALTIME_DO_WAKE_PATH) {
             return this.#handleWake(request);
         }
@@ -150,7 +158,41 @@ export class SyncularRealtimeHost {
         }
         return new Response('not found', { status: 404 });
     }
-    /** §8.3 wake: an HTTP push landed in a plain isolate; re-pull the delta. */
+    #serializePartition(operation) {
+        const result = this.#partitionTail.then(operation, operation);
+        this.#partitionTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async #handleSync(request) {
+        const contentType = request.headers
+            .get('content-type')
+            ?.split(';')[0]
+            ?.trim();
+        if (contentType !== SSP2_CONTENT_TYPE) {
+            const error = new SyncError('sync.invalid_request', 'unsupported content type');
+            return Response.json(errorBody(error), { status: 415 });
+        }
+        const identity = readRequestIdentityHeaders(request);
+        if (identity === undefined) {
+            const error = new SyncError('sync.auth_required');
+            return Response.json(errorBody(error), { status: error.httpStatus });
+        }
+        try {
+            const bytes = new Uint8Array(await request.arrayBuffer());
+            const out = await handleSyncRequest(bytes, this.#getHub().requestContextFor(identity));
+            return new Response(out.slice().buffer, {
+                status: 200,
+                headers: { 'content-type': SSP2_CONTENT_TYPE },
+            });
+        }
+        catch (error) {
+            const sync = error instanceof SyncError
+                ? error
+                : new SyncError('sync.invalid_request', String(error));
+            return Response.json(errorBody(sync), { status: sync.httpStatus });
+        }
+    }
+    /** §8.3 wake: an external coordinated command landed; re-pull the delta. */
     async #handleWake(request) {
         const body = (await request.json().catch(() => null));
         const partition = body?.partition;
@@ -235,16 +277,18 @@ export class SyncularRealtimeHost {
     }
     /** Hibernation callback: an inbound frame. */
     async webSocketMessage(ws, message) {
-        const session = await this.#sessionFor(ws);
-        if (session === undefined)
-            return;
-        if (typeof message === 'string') {
-            session.handleMessage(message);
-        }
-        else {
-            // §8.7: tagged binary — sync-round request chunks / acks.
-            session.handleBinary(new Uint8Array(message));
-        }
+        await this.#serializePartition(async () => {
+            const session = await this.#sessionFor(ws);
+            if (session === undefined)
+                return;
+            if (typeof message === 'string') {
+                await session.handleMessage(message);
+            }
+            else {
+                // §8.7: tagged binary — sync-round request chunks / acks.
+                await session.handleBinary(new Uint8Array(message));
+            }
+        });
     }
     /** Hibernation callback: the socket closed. */
     async webSocketClose(ws) {
@@ -316,6 +360,10 @@ const REALTIME_ID_HEADER = {
     actorId: 'x-syncular-actor',
     clientId: 'x-syncular-client',
 };
+export function writeRequestIdentityHeaders(headers, identity) {
+    headers.set(REALTIME_ID_HEADER.partition, identity.partition);
+    headers.set(REALTIME_ID_HEADER.actorId, identity.actorId);
+}
 /** Write the resolved identity onto an upgrade request's headers (Worker side). */
 export function writeIdentityHeaders(headers, identity) {
     headers.set(REALTIME_ID_HEADER.partition, identity.partition);
@@ -335,3 +383,14 @@ function readIdentityHeaders(request) {
     }
     return { partition, actorId, clientId };
 }
+function readRequestIdentityHeaders(request) {
+    const partition = request.headers.get(REALTIME_ID_HEADER.partition);
+    const actorId = request.headers.get(REALTIME_ID_HEADER.actorId);
+    if (partition === null ||
+        partition === '' ||
+        actorId === null ||
+        actorId === '') {
+        return undefined;
+    }
+    return { partition, actorId };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server-workers",
-  "version": "0.15.23",
+  "version": "0.15.25",
   "description": "Cloudflare Workers adapter for the Syncular sync server",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -45,11 +45,11 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/server": "0.15.23",
-    "@syncular/server-hono": "0.15.23",
+    "@syncular/server": "0.15.25",
+    "@syncular/server-hono": "0.15.25",
     "hono": "^4.11.0"
   },
   "devDependencies": {
-    "@syncular/core": "0.15.23"
+    "@syncular/core": "0.15.25"
   }
 }

package/src/index.ts

@@ -21,16 +21,17 @@
  * `SyncularRealtimeDO` (`realtime-do.ts`): one DO per partition hosting the
  * `RealtimeHub`, WebSocket hibernation driving the existing `RealtimeSession`,
  * in-DO commit fan-out, storage over the same D1 binding. Pass a
- * `realtime` option to `createWorkersFetchHandler` to mount the `/realtime`
- * upgrade route + the HTTP-push wake path; omit it for an HTTP-only
- * deployment (still fully conformant per §1.1 — clients sync over `POST
- * /sync`, identical semantics). No fallback is implied either way: HTTP-only
- * is a smaller complete deployment, not a degraded one.
+ * `realtime` option to mount `/realtime`; its namespace also coordinates D1
+ * `/sync`. An HTTP-only D1 deployment uses the `coordinator` option instead:
+ * WebSockets are optional, the per-partition push queue is not.
  */
 import {
   type D1Database,
   D1ServerStorage,
+  errorBody,
+  SSP2_CONTENT_TYPE,
   type StoredCommit,
+  SyncError,
   type SyncServerConfig,
 } from '@syncular/server';
 import {
@@ -41,7 +42,9 @@ import {
   REALTIME_DO_UPGRADE_PATH,
   REALTIME_DO_WAKE_PATH,
   type RealtimeUpgradeIdentity,
+  SYNC_DO_REQUEST_PATH,
   writeIdentityHeaders,
+  writeRequestIdentityHeaders,
 } from './realtime-do';
 
 export { type D1Database, D1ServerStorage } from '@syncular/server';
@@ -84,10 +87,8 @@ export interface DurableObjectIdLike {
 
 /**
  * Realtime wiring for `createWorkersFetchHandler`. Supplying it mounts the
- * `GET <mount>/realtime` upgrade route and the HTTP-push wake path (the
- * `RealtimeNotifier` returned by `durableObjectRealtimeNotifier`, which the
- * host spreads into its `SyncServerConfig.realtime` so a push landing in the
- * plain isolate wakes the partition's DO).
+ * `GET <mount>/realtime` upgrade route and uses the same namespace as the D1
+ * `/sync` coordinator.
  */
 export interface WorkersRealtimeOptions {
   /** The DO namespace binding (wrangler `[[durable_objects.bindings]]`). */
@@ -114,9 +115,25 @@ export type WorkersRealtimeFactory<Env = unknown> = (
   ctx: ExecutionContextLike,
 ) => WorkersRealtimeOptions | Promise<WorkersRealtimeOptions>;
 
+/** Per-partition Durable Object boundary for D1 sync rounds without WS. */
+export interface WorkersCoordinatorOptions {
+  readonly namespace: DurableObjectNamespaceLike;
+}
+
+export type WorkersCoordinatorFactory<Env = unknown> = (
+  env: Env,
+  ctx: ExecutionContextLike,
+) => WorkersCoordinatorOptions | Promise<WorkersCoordinatorOptions>;
+
 export interface WorkersFetchHandlerOptions<Env = unknown> {
   /** Build the HTTP handler config + auth per request (see the type doc). */
   readonly config: WorkersConfigFactory<Env>;
+  /**
+   * Serialize D1 `/sync` rounds through one Durable Object per partition.
+   * Required for D1 pushes when `realtime` is omitted. If `realtime` is
+   * present its namespace is the coordinator automatically.
+   */
+  readonly coordinator?: WorkersCoordinatorFactory<Env>;
   /**
    * Realtime (§8) over a Durable Object. Omit for an HTTP-only deployment
    * (still fully conformant — clients sync over `POST /sync`).
@@ -178,17 +195,60 @@ export function createWorkersFetchHandler<Env = unknown>(
       : factoryOrOptions;
   return async (request, env, ctx) => {
     // §8 upgrade: GET <mount>/realtime → forward to the partition's DO.
+    let realtime: WorkersRealtimeOptions | undefined;
     if (options.realtime !== undefined) {
-      const realtime = await options.realtime(env, ctx);
+      realtime = await options.realtime(env, ctx);
       const upgraded = await handleRealtimeUpgrade(request, realtime);
       if (upgraded !== undefined) return upgraded;
     }
     const honoOptions = await options.config(env, ctx);
+    const coordinator =
+      options.coordinator !== undefined
+        ? await options.coordinator(env, ctx)
+        : realtime;
+    if (coordinator !== undefined && isSyncPost(request)) {
+      const auth = await honoOptions.authenticate(request);
+      if (auth === null) {
+        const error = new SyncError('sync.auth_required');
+        return Response.json(errorBody(error), { status: error.httpStatus });
+      }
+      return forwardSyncRequest(request, coordinator.namespace, auth);
+    }
     const app = createSyncularHono(honoOptions);
     return app.fetch(request);
   };
 }
 
+function isSyncPost(request: Request): boolean {
+  if (request.method !== 'POST') return false;
+  const contentType = request.headers
+    .get('content-type')
+    ?.split(';')[0]
+    ?.trim();
+  if (contentType !== SSP2_CONTENT_TYPE) return false;
+  const pathname = new URL(request.url).pathname;
+  return pathname === '/sync' || pathname.endsWith('/sync');
+}
+
+/**
+ * Forward an authenticated HTTP sync round to the partition's Durable Object.
+ * Pulls and pushes share this path so client-record updates and push apply use
+ * one ordered partition boundary. Other HTTP routes remain direct.
+ */
+export function forwardSyncRequest(
+  request: Request,
+  namespace: DurableObjectNamespaceLike,
+  identity: { readonly partition: string; readonly actorId: string },
+): Promise<Response> {
+  const stub = namespace.get(namespace.idFromName(identity.partition));
+  const forwarded = new Request(
+    new URL(SYNC_DO_REQUEST_PATH, request.url),
+    request,
+  );
+  writeRequestIdentityHeaders(forwarded.headers, identity);
+  return stub.fetch(forwarded);
+}
+
 /**
  * If `request` is the `GET <mount>/realtime` upgrade, authenticate it and
  * forward it to the partition's DO stub; otherwise return `undefined` so the
@@ -233,13 +293,14 @@ export function forwardRealtimeUpgrade(
 }
 
 /**
- * A `RealtimeNotifier` (§8.2) that wakes the partition's DO after a push lands
- * via the plain HTTP handler (a stateless isolate with no sockets). The DO
+ * A `RealtimeNotifier` (§8.2) for an external authoritative command host that
+ * already serializes its D1 writes and must wake the partition's DO. The DO
  * calls `hub.wake(partition, 'catchup-required')` and its sockets re-pull the
  * delta from the shared D1 (§8.3) — the Workers in-platform analogue of the
  * Postgres LISTEN/NOTIFY fan-out. A wake, not a byte re-broadcast.
  *
- * Spread this into `SyncServerConfig.realtime`. The wake is fire-and-forget:
+ * Ordinary Workers `/sync` does not need this: it already lands on the DO and
+ * fans out in-process. This wake is fire-and-forget:
  * a DO fetch failure never fails the push (the commit is already durable in
  * D1; the client's next pull or reconnect self-heals).
  */

package/src/realtime-do.ts

@@ -7,9 +7,9 @@
  *
  * One DO instance hosts **one `RealtimeHub`** and serves **one partition**
  * (the DO id is `idFromName(partition)`, see `realtimeStubFor`). All of a
- * partition's sockets and its commit fan-out live in that single-threaded DO —
- * which is also the per-partition write-serialization point the D1 storage
- * wants (see `d1-storage.ts` "Concurrency posture"). Because the hub is the
+ * partition's sync rounds, sockets, and commit fan-out live behind its
+ * explicit FIFO — the per-partition serialization point D1 requires. Because
+ * the hub is the
  * `RealtimeNotifier` (§8.2) *inside* the DO, a sync round that lands over the
  * socket fans its full delta out to the partition's other sockets with no
  * LISTEN/NOTIFY — writes and sockets are co-located.
@@ -60,23 +60,23 @@
  * fields `connect` needs. Everything else (`cursor`, `registrations`,
  * `lastKnownSeq`) is re-derived from D1 by `connect`, which is authoritative.
  *
- * ## The wake path (HTTP-push fan-out, the LISTEN/NOTIFY analogue)
+ * ## The wake path (external-command fan-out)
  *
- * A push landing via the *plain* Workers `fetch` handler (a stateless isolate,
- * not the DO) has applied a commit to D1 but has no in-memory sockets. It
- * wakes the partition's DO by `stub.fetch`-ing the internal `/__wake` endpoint
- * with the partition + commitSeq; the DO calls `hub.wake(partition,
- * 'catchup-required')` and its sockets re-pull the delta from the shared D1
- * (§8.3). This is the Workers in-platform equivalent of Postgres LISTEN/NOTIFY
- * — a wake, not a byte re-broadcast, so remote sessions pay one re-pull. See
- * `durableObjectRealtimeNotifier` in `index.ts` for the caller side.
+ * Ordinary HTTP `/sync` is forwarded into this DO and fans out in-process. An
+ * external authoritative command host that already provides equivalent D1
+ * partition serialization may call `/__wake` after its own commit so sockets
+ * re-pull. See `durableObjectRealtimeNotifier` for that caller side.
  */
 import {
   createRealtimeHub,
   D1ServerStorage,
+  errorBody,
+  handleSyncRequest,
   type RealtimeHub,
   type RealtimeHubConfig,
   type RealtimeSession,
+  SSP2_CONTENT_TYPE,
+  SyncError,
 } from '@syncular/server';
 
 // -- The Durable Object platform surface this class uses (structural) -------
@@ -103,17 +103,26 @@ export type WebSocketPairLike = { 0: WebSocketLike; 1: WebSocketLike };
 /**
  * The host env a `SyncularRealtimeDO` reads. Supplied by the DO runtime via
  * the class constructor's second arg. `DB` is the D1 binding (the same one the
- * plain HTTP handler uses); `configFactory` builds the hub config from `env`.
+ * outer Worker config uses); `configFactory` builds the hub config from `env`.
  */
-export interface RealtimeDOConfig {
-  /**
-   * Build the realtime hub config for this DO from its D1 storage. Mirrors the
-   * HTTP handler's config: same schema, same `resolveScopes`, same segment
-   * store (§8.7 socket rounds need it) — so a socket round and a `POST /sync`
-   * round are the SAME handler over the SAME storage.
-   */
-  hubConfig(storage: D1ServerStorage): RealtimeHubConfigInput;
-}
+export type RealtimeDOConfig =
+  | {
+      /**
+       * Preferred: build the complete canonical sync config around the DO's
+       * coordinated D1 storage. Reuse this factory for the outer HTTP adapter
+       * so HTTP-forwarded and socket rounds cannot drift by capability.
+       */
+      syncConfig(storage: D1ServerStorage): RealtimeHubConfig;
+      readonly hubConfig?: never;
+    }
+  | {
+      /**
+       * @deprecated Use `syncConfig`. This compatibility shape predates the
+       * canonical HTTP/realtime capability contract.
+       */
+      hubConfig(storage: D1ServerStorage): RealtimeHubConfigInput;
+      readonly syncConfig?: never;
+    };
 
 /**
  * The subset of `RealtimeHubConfig` the DO host supplies (storage is wired by
@@ -148,6 +157,7 @@ export interface RealtimeUpgradeIdentity {
 /** Internal control-request paths on the DO stub (never client-facing). */
 export const REALTIME_DO_WAKE_PATH = '/__syncular_realtime/wake';
 export const REALTIME_DO_UPGRADE_PATH = '/__syncular_realtime/upgrade';
+export const SYNC_DO_REQUEST_PATH = '/__syncular_realtime/sync';
 
 /**
  * The base `SyncularRealtimeDO`. A host subclasses (or instantiates) it with a
@@ -183,6 +193,8 @@ export class SyncularRealtimeHost {
   /** Sockets whose rehydration `hello` must be swallowed (already greeted at
    * the real upgrade — rehydration is transparent to the client). */
   readonly #swallowHello = new Set<WebSocketLike>();
+  /** Explicit FIFO: Durable Object events may interleave at `await`. */
+  #partitionTail: Promise<void> = Promise.resolve();
 
   constructor(
     state: DurableObjectStateLike,
@@ -191,19 +203,28 @@ export class SyncularRealtimeHost {
   ) {
     this.#state = state;
     this.#storage = new D1ServerStorage(db, {
-      // This host is one Durable Object per partition, so the §6.8 storage
-      // precondition is true for socket rounds handled inside the object.
-      commitValidationSerialized: true,
+      // Every HTTP/socket sync round enters #serializePartition before this
+      // storage is used. One DO is selected per partition.
+      pushApplySerialized: true,
     });
     this.#config = config;
   }
 
   #getHub(): RealtimeHub {
     if (this.#hub === undefined) {
-      this.#hub = createRealtimeHub({
-        ...this.#config.hubConfig(this.#storage),
-        storage: this.#storage,
-      });
+      const config =
+        this.#config.syncConfig !== undefined
+          ? this.#config.syncConfig(this.#storage)
+          : {
+              ...this.#config.hubConfig(this.#storage),
+              storage: this.#storage,
+            };
+      if (config.storage !== this.#storage) {
+        throw new Error(
+          'RealtimeDOConfig.syncConfig must use the coordinated storage argument',
+        );
+      }
+      this.#hub = createRealtimeHub(config);
     }
     return this.#hub;
   }
@@ -212,10 +233,13 @@ export class SyncularRealtimeHost {
    * The DO `fetch` handler: routes the internal upgrade + wake control paths.
    * The Worker forwards `GET <mount>/realtime` here as an upgrade with the
    * resolved identity in headers (see `forwardRealtimeUpgrade` in `index.ts`),
-   * and forwards HTTP-push wakes to `/__syncular_realtime/wake`.
+   * and accepts external-command wakes at `/__syncular_realtime/wake`.
    */
   async fetch(request: Request): Promise<Response> {
     const url = new URL(request.url);
+    if (url.pathname === SYNC_DO_REQUEST_PATH) {
+      return this.#serializePartition(() => this.#handleSync(request));
+    }
     if (url.pathname === REALTIME_DO_WAKE_PATH) {
       return this.#handleWake(request);
     }
@@ -225,7 +249,52 @@ export class SyncularRealtimeHost {
     return new Response('not found', { status: 404 });
   }
 
-  /** §8.3 wake: an HTTP push landed in a plain isolate; re-pull the delta. */
+  #serializePartition<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.#partitionTail.then(operation, operation);
+    this.#partitionTail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+
+  async #handleSync(request: Request): Promise<Response> {
+    const contentType = request.headers
+      .get('content-type')
+      ?.split(';')[0]
+      ?.trim();
+    if (contentType !== SSP2_CONTENT_TYPE) {
+      const error = new SyncError(
+        'sync.invalid_request',
+        'unsupported content type',
+      );
+      return Response.json(errorBody(error), { status: 415 });
+    }
+    const identity = readRequestIdentityHeaders(request);
+    if (identity === undefined) {
+      const error = new SyncError('sync.auth_required');
+      return Response.json(errorBody(error), { status: error.httpStatus });
+    }
+    try {
+      const bytes = new Uint8Array(await request.arrayBuffer());
+      const out = await handleSyncRequest(
+        bytes,
+        this.#getHub().requestContextFor(identity),
+      );
+      return new Response(out.slice().buffer as ArrayBuffer, {
+        status: 200,
+        headers: { 'content-type': SSP2_CONTENT_TYPE },
+      });
+    } catch (error) {
+      const sync =
+        error instanceof SyncError
+          ? error
+          : new SyncError('sync.invalid_request', String(error));
+      return Response.json(errorBody(sync), { status: sync.httpStatus });
+    }
+  }
+
+  /** §8.3 wake: an external coordinated command landed; re-pull the delta. */
   async #handleWake(request: Request): Promise<Response> {
     const body = (await request.json().catch(() => null)) as {
       partition?: unknown;
@@ -321,14 +390,16 @@ export class SyncularRealtimeHost {
     ws: WebSocketLike,
     message: ArrayBuffer | string,
   ): Promise<void> {
-    const session = await this.#sessionFor(ws);
-    if (session === undefined) return;
-    if (typeof message === 'string') {
-      session.handleMessage(message);
-    } else {
-      // §8.7: tagged binary — sync-round request chunks / acks.
-      session.handleBinary(new Uint8Array(message));
-    }
+    await this.#serializePartition(async () => {
+      const session = await this.#sessionFor(ws);
+      if (session === undefined) return;
+      if (typeof message === 'string') {
+        await session.handleMessage(message);
+      } else {
+        // §8.7: tagged binary — sync-round request chunks / acks.
+        await session.handleBinary(new Uint8Array(message));
+      }
+    });
   }
 
   /** Hibernation callback: the socket closed. */
@@ -414,6 +485,14 @@ const REALTIME_ID_HEADER = {
   clientId: 'x-syncular-client',
 } as const;
 
+export function writeRequestIdentityHeaders(
+  headers: Headers,
+  identity: { readonly partition: string; readonly actorId: string },
+): void {
+  headers.set(REALTIME_ID_HEADER.partition, identity.partition);
+  headers.set(REALTIME_ID_HEADER.actorId, identity.actorId);
+}
+
 /** Write the resolved identity onto an upgrade request's headers (Worker side). */
 export function writeIdentityHeaders(
   headers: Headers,
@@ -442,6 +521,22 @@ function readIdentityHeaders(
   return { partition, actorId, clientId };
 }
 
+function readRequestIdentityHeaders(
+  request: Request,
+): { readonly partition: string; readonly actorId: string } | undefined {
+  const partition = request.headers.get(REALTIME_ID_HEADER.partition);
+  const actorId = request.headers.get(REALTIME_ID_HEADER.actorId);
+  if (
+    partition === null ||
+    partition === '' ||
+    actorId === null ||
+    actorId === ''
+  ) {
+    return undefined;
+  }
+  return { partition, actorId };
+}
+
 // -- Minimal ambient types (structural; not the real workers-types) ---------
 
 /** The D1 binding, re-declared structurally (see `d1-storage.ts`). */