orez-sync-cf-host 0.4.52

package/README.md

@@ -0,0 +1,143 @@
+# `sync-cf-host`
+
+This is the production-shaped Cloudflare Durable Object host for the Rust sync
+engine. The package exposes a consumer integration surface (`createSyncWorker`,
+`createSyncDurableObject`, `registerMutators`) and a harness deployment built
+from `src/harness-worker.ts`. Consumers provide a JSON Zero schema, application
+DDL/seed initializer, normalized-claims authenticator, mutator registry, and an
+optional row-visibility hook.
+
+The Worker authenticates at the consumer edge, forwards only normalized claims
+to a per-namespace Durable Object, and never logs tokens, mutation arguments, or
+row contents. Pull runs `engine_handle_pull` inside `transactionSync`; push runs
+Rust `push_validate`/`preflight`/`finalize`/`record_app_error` steps around the
+registered asynchronous TypeScript mutator inside `ctx.storage.transaction`.
+Every SQL cursor is materialized before an await. Application effects are
+collected and run only after their transaction commits; application failures use
+the required second transaction to advance the LMID marker.
+
+## 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
+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.
+
+`/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
+deterministic model resets in-memory state and changes boot ID while retaining
+SQLite state and sockets. This models the harness/cf idle-teardown pattern; it
+does not claim that a real platform eviction happens on a 5-second schedule.
+
+## Authenticated operator controls
+
+All `/admin/*` routes are rejected unless the consumer's `authorizeAdmin`
+callback succeeds or the request presents the deployment's `ADMIN_KEY` through
+`x-admin-key`. Harness and operator deployments expose `/admin/status`; it
+includes the persisted writer-enabled state and wasm linear-memory byte length
+in addition to the engine/counter fields above.
+
+`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
+one writer and prove rejection before enabling another. The test-only runner is:
+
+```sh
+mise exec node@24.3.0 -- bun harness/src/rollback-drill.ts --confirm-test-only
+```
+
+The runner accepts only loopback or the `lslcf.workers.dev` test worker and does
+not mutate a production route. These controls are mechanisms, not authorization
+to perform a production cutover.
+
+## Counter and HTTP wire representation
+
+Inside the wasm/JavaScript engine boundary, cookies, watermarks, and LMIDs are
+canonical decimal strings (`0` or non-zero ASCII digits), parsed as signed
+SQLite-range `i64`; exact SQLite reads use `CAST(... AS TEXT)`. The baseline HTTP
+wire remains JSON numbers for Zero 1.7 byte compatibility, accepted only within
+the JavaScript safe-integer range. M1 centralizes this conversion in
+`sync-core::wire::counter_to_json` and accepts either representation inbound.
+No engine code silently converts an unsafe persisted counter through a JS
+`Number`.
+
+## Local checks
+
+```sh
+cd packages/sync-cf-host
+bun install
+bun run typecheck             # builds probe-enabled wasm for all TS declarations
+bun run test:platform         # M0 boundary regression: 36 local workerd assertions
+bun run test:integration      # production host: pull/push/rollback/wake/eviction
+bun run bundle                # Wrangler dry-run bundle report
+bun run measure               # cold start/CPU/storage/memory baseline
+cargo test -p sync-core       # engine/model/reference/soot suites (from repo root)
+```
+
+The production integration suite can target a deployed Worker:
+
+```sh
+M3_BASE_URL=https://orez-rust-sync.lslcf.workers.dev \
+M3_ADMIN_KEY="$(tr -d '\n' < ~/.zharness-cf-admin-key)" \
+bun integration-test.mjs
+```
+
+The platform regression remains a separate feature-enabled test path so probe
+helpers are absent from the production wasm bundle:
+
+```sh
+bun run test:platform
+```
+
+## M3 measurements
+
+Measured 2026-07-10 UTC on darwin-arm64, Bun 1.3.10, Rust 1.94.0,
+wasm-pack 0.14.0, Wrangler 4.103.0, workerd 1.20260617.1. Local workerd was
+started with the production `orez-rust-sync` config and an equivalent local
+admin variable; deployed requests used the `lslcf` account and returned a
+Cloudflare LAX edge (`cf-ray …-LAX`).
+
+| Measurement                                                          | Result                                                                |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Local production integration                                         | 16 assertions passed                                                  |
+| Deployed production integration                                      | 16 assertions passed                                                  |
+| Local M0 platform regression                                         | 36 assertions passed                                                  |
+| Rust core tests                                                      | 27 reference + 13 composition + 2 model tests passed                  |
+| Bundle upload                                                        | 328.34 KiB total; 130.45 KiB gzip                                     |
+| Wasm module                                                          | approximately 273 KiB on disk                                         |
+| Wrangler reported startup                                            | 1 ms                                                                  |
+| Local cold DO pull (30 namespaces)                                   | p50 5.362 ms; p95 7.081 ms                                            |
+| Local push acknowledgement (50 mutations)                            | p50 1.507 ms; p95 2.971 ms                                            |
+| Seeded storage                                                       | 81,920 bytes                                                          |
+| Storage after 50 pushes                                              | 90,112 bytes (+8,192 bytes)                                           |
+| Local workerd RSS                                                    | 97.391 MiB baseline; 146.625 MiB after load (+49.234 MiB process RSS) |
+| CF eviction lane                                                     | boot ID changed; 20 writes; 126 pulls; zero 409s; monotone cookies    |
+| CF wake-only storm (100 clients, 5 writers, 10 s safety poll)        | propagation p50/p95 809/810 ms                                        |
+| CF clean-write propagation (10 clients, 20 writes, 10 s safety poll) | commit-to-seen p50/p95 136/406 ms; issue-to-seen p95 858 ms           |
+| CF 10-client/2-writer bench                                          | ack p50/p95 178/243 ms; propagation p50/p95 381/524 ms                |
+| Equivalent TS DO bench                                               | ack p50/p95 165/903 ms; propagation p50/p95 583/1,074 ms              |
+
+Wake fan-out is anchored with `waitUntil` after commit and is not on the push
+response's critical path. The acknowledgement result is a local wall-time
+proxy, not billed Cloudflare CPU. RSS is the whole local
+workerd process, not an isolate allocation; Cloudflare's 128 MiB per-isolate
+limit cannot be inferred from that process number. The bundle is 95.8% below
+the 3 MiB gzip Free-plan limit (and 98.7% below the 10 MiB paid-plan limit).
+See [Cloudflare Worker limits](https://developers.cloudflare.com/workers/platform/limits/).
+
+## Deployment
+
+`wrangler.toml` is checked in with Worker name `orez-rust-sync`, SQLite Durable
+Object class `SyncDurableObject`, and account `6afff1f79e2fd12f1cfd1bfe1dfd08d1`.
+The deployed test version used for this M3 pass was
+`871a13df-7c3b-4e1c-bc90-c3cbd00f2dea` at
+`https://orez-rust-sync.lslcf.workers.dev`. The throwaway M0 Worker was already
+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).

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "orez-sync-cf-host",
+  "version": "0.4.52",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.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",
+    "test:integration": "bun run build:wasm && bun integration-test.mjs",
+    "test:ingest": "bun run build:wasm && bun ingest-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",
+    "typescript": "5.9.3",
+    "workerd": "1.20260617.1",
+    "wrangler": "4.103.0"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/config.ts

@@ -0,0 +1,47 @@
+import type { PullCaps, SyncHostConfig, SyncHostEnv } from './types.js'
+
+export function validatePullCaps(caps: PullCaps): PullCaps {
+  if (!Number.isSafeInteger(caps.maxChangeRows) || caps.maxChangeRows < 1) {
+    throw new TypeError('caps.maxChangeRows must be a positive safe integer')
+  }
+  return caps
+}
+
+export function validateSyncHostConfig<Env extends SyncHostEnv>(
+  config: SyncHostConfig<Env>
+): SyncHostConfig<Env> {
+  const hasMutators = config.mutators !== undefined
+  const hasDelegate = config.mutateUrl !== undefined
+  if (hasMutators === hasDelegate) {
+    throw new TypeError('sync host config requires exactly one of mutators or mutateUrl')
+  }
+  if (hasDelegate && !config.upstream) {
+    throw new TypeError('sync host config mutateUrl requires upstream')
+  }
+  if (config.mutateBinding !== undefined && !hasDelegate) {
+    throw new TypeError('sync host config mutateBinding requires mutateUrl')
+  }
+  if (config.mutateBinding !== undefined && !config.mutateBinding) {
+    throw new TypeError('sync host config mutateBinding must not be empty')
+  }
+  if (hasMutators && config.upstream) {
+    throw new TypeError(
+      'sync host config cannot combine local mutators with upstream ingest'
+    )
+  }
+  if (config.mutateUrl && !config.mutateUrl.startsWith('/')) {
+    throw new TypeError('mutateUrl must be an absolute path')
+  }
+  if (config.upstream) {
+    if (!config.upstream.binding) throw new TypeError('upstream.binding is required')
+    const limit = config.upstream.changeLimit ?? 1_000
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 10_000) {
+      throw new TypeError('upstream.changeLimit must be a safe integer in 1..10000')
+    }
+    const interval = config.upstream.intervalMs ?? 15_000
+    if (!Number.isSafeInteger(interval) || interval < 1_000) {
+      throw new TypeError('upstream.intervalMs must be a safe integer >= 1000')
+    }
+  }
+  return config
+}

package/src/generated/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "sync-wasm",
+  "type": "module",
+  "version": "0.1.0",
+  "license": "MIT",
+  "files": [
+    "sync_wasm_bg.wasm",
+    "sync_wasm.js",
+    "sync_wasm.d.ts"
+  ],
+  "main": "sync_wasm.js",
+  "types": "sync_wasm.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ]
+}

package/src/generated/sync_wasm.d.ts

@@ -0,0 +1,123 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Apply one ordered page from the upstream ZeroSqlDO change feed. The host
+ * owns one transaction around this call; application triggers append the
+ * ordinary engine change-log entries consumed by pull/CVR code.
+ */
+export function engine_apply_upstream(db: any, schema: any, batch: any): any;
+
+/**
+ * Atomically rebuild application rows from a point-in-time upstream snapshot.
+ */
+export function engine_apply_upstream_snapshot(db: any, schema: any, snapshot: any): any;
+
+export function engine_assemble_push_response(results: any): 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_finalize(db: any, client_group_id: string, client_id: string, mutation_id: string): void;
+
+/**
+ * Production pull entry. The TypeScript host owns `transactionSync`.
+ */
+export function engine_handle_pull(db: any, schema: any, visibility: any, caps: any, retain_changes: string, body: any, user_id: string): any;
+
+/**
+ * Query-aware pull entry point. Desired-query ASTs are already resolved and
+ * validated by the consumer host before crossing this boundary.
+ */
+export function engine_handle_query_pull(db: any, schema: any, retain_changes: string, body: any, user_id: string): any;
+
+/**
+ * Initialize the additive query-aware durable tables. The host owns the
+ * transaction boundary, exactly as it does for the baseline schema.
+ */
+export function engine_init_query_schema(db: any): void;
+
+/**
+ * Initialize the sync engine's durable metadata and triggers. The host calls
+ * this inside startup `transactionSync` after application DDL and seed.
+ */
+export function engine_init_schema(db: any, schema: any): void;
+
+export function engine_invalidate(db: any): void;
+
+/**
+ * Linear-memory size for authenticated operator soak diagnostics. This is a
+ * byte count only; it contains no application or query data.
+ */
+export function engine_memory_bytes(): number;
+
+export function engine_preflight(db: any, client_group_id: string, client_id: string, mutation_id: string, user_id: string): any;
+
+export function engine_prune(db: any, retain_changes: string): void;
+
+/**
+ * Validate an entire push before the host opens the first mutation tx.
+ */
+export function engine_push_validate(body: 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;
+
+export function engine_version(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    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_finalize: (a: any, b: number, c: number, d: number, e: number, f: number, g: 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];
+    readonly engine_init_schema: (a: any, b: any) => [number, number];
+    readonly engine_invalidate: (a: any) => [number, number];
+    readonly engine_memory_bytes: () => [number, number, number];
+    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_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];
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;