orez-sync-cf-host 0.12.1 → 0.12.3

package/dist/generated/sync_wasm.d.ts

@@ -105,6 +105,12 @@ 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;
 
+/**
+ * Identity of the durable DDL this engine build installs. Hosts fold it into
+ * the fingerprint that lets an up-to-date namespace skip the schema pass.
+ */
+export function engine_schema_revision(): string;
+
 export function engine_state(db: any): any;
 
 export function engine_version(): string;
@@ -133,6 +139,7 @@ export interface InitOutput {
     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_schema_revision: () => [number, number];
     readonly engine_state: (a: any) => [number, number, number];
     readonly engine_version: () => [number, number];
     readonly __wbindgen_malloc: (a: number, b: number) => number;

package/dist/generated/sync_wasm.js

@@ -352,6 +352,24 @@ export function engine_record_app_error(db, client_group_id, client_id, mutation
     }
 }
 
+/**
+ * Identity of the durable DDL this engine build installs. Hosts fold it into
+ * the fingerprint that lets an up-to-date namespace skip the schema pass.
+ * @returns {string}
+ */
+export function engine_schema_revision() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.engine_schema_revision();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
 /**
  * @param {any} db
  * @returns {any}

package/dist/generated/sync_wasm_bg.js

@@ -350,6 +350,24 @@ export function engine_record_app_error(db, client_group_id, client_id, mutation
     }
 }
 
+/**
+ * Identity of the durable DDL this engine build installs. Hosts fold it into
+ * the fingerprint that lets an up-to-date namespace skip the schema pass.
+ * @returns {string}
+ */
+export function engine_schema_revision() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.engine_schema_revision();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
 /**
  * @param {any} db
  * @returns {any}

package/dist/host.js

@@ -1,11 +1,11 @@
 import { DurableObject } from 'cloudflare:workers';
-import { createSyncExecutor } from 'orez-sync-executor/core';
+import { createSyncExecutor, isMutationRetryError } from 'orez-sync-executor/core';
 import { createSocketHost } from 'orez-sync-executor/realtime';
 import { validateSyncHostConfig } from './config.js';
 import { createQueryCompiler } from './query-compiler.js';
 import { resolveQueryPatch } from './query-patch.js';
 import { decodeSqlParams, SqlStorageDirect, SqlStorageMutatorTransaction, SqlStorageSyncDb, } from './sql-storage-adapter.js';
-import { engine_authorize_realtime_subscription, engine_apply_snapshot_changes, engine_apply_snapshot_page, engine_apply_upstream, engine_begin_snapshot_generation, engine_finalize, engine_finalize_snapshot_generation, engine_handle_query_pull, engine_init_query_schema, engine_init_schema, engine_invalidate, engine_memory_bytes, engine_preflight, engine_prune, engine_push_validate, engine_read_snapshot_progress, engine_state, engine_version, } from './wasm.js';
+import { engine_authorize_realtime_subscription, engine_apply_snapshot_changes, engine_apply_snapshot_page, engine_apply_upstream, engine_begin_snapshot_generation, engine_finalize, engine_finalize_snapshot_generation, engine_handle_query_pull, engine_init_query_schema, engine_init_schema, engine_invalidate, engine_memory_bytes, engine_preflight, engine_prune, engine_push_validate, engine_read_snapshot_progress, engine_schema_revision, engine_state, engine_version, } from './wasm.js';
 import { IngestBreakerError, IngestCircuitBreaker, retryDelayMs, shouldRetryDelegatedPush, } from './write-safeguards.js';
 const NAMESPACE_HEADER = 'x-orez-sync-namespace';
 const UPSTREAM_PATH_HEADER = 'x-orez-sync-upstream-path';
@@ -31,10 +31,10 @@ function freshCounters() {
         externalEffectFailures: 0,
     };
 }
-function json(value, status = 200) {
+function json(value, status = 200, headers) {
     return Response.json(value, {
         status,
-        headers: { 'cache-control': 'no-store' },
+        headers: { 'cache-control': 'no-store', ...headers },
     });
 }
 function isStructuredPushFailed(value) {
@@ -67,8 +67,29 @@ function errorBody(error) {
             retryAfterMs: error.retryAfterMs,
         };
     }
+    if (isMutationRetryError(error)) {
+        // the reason travels in `details` so a caller can pace on why it was
+        // refused. it used to arrive as an acknowledged app error, which cost a
+        // ledger write per refusal and consumed the mutation.
+        return {
+            error: errorMessage(error),
+            ...(error.details === undefined ? {} : { details: error.details }),
+            retryAfterMs: error.retryAfterMs,
+        };
+    }
     return { error: errorMessage(error) };
 }
+// one response builder for every refusal, so a rejection that tells the caller
+// when to come back always says so in the header an HTTP client already reads.
+function errorResponse(error) {
+    const body = errorBody(error);
+    const retryAfterMs = body.retryAfterMs;
+    // whole seconds on the wire, rounded up: rounding down invites the caller
+    // back while the window it has to wait out is still open.
+    return json(body, statusOf(error), typeof retryAfterMs === 'number'
+        ? { 'retry-after': String(Math.ceil(retryAfterMs / 1000)) }
+        : undefined);
+}
 function requestError(message, status = 400) {
     return Object.assign(new Error(message), { status });
 }
@@ -209,7 +230,7 @@ export function createSyncWorker(config) {
                         forwardedBody = { claims, body };
                     }
                     catch (error) {
-                        return json(errorBody(error), statusOf(error));
+                        return errorResponse(error);
                     }
                 }
             }
@@ -264,10 +285,12 @@ export function createSyncDurableObject(config) {
         #executor;
         #executorBeforeCommitFault = null;
         #bootID = crypto.randomUUID();
+        #initSkipped = false;
         #lastRequestAt = 0;
         #hibernations = 0;
         #dropNextPushResponse = false;
         #counters = freshCounters();
+        #sqlBilling = { rowsRead: 0, rowsWritten: 0 };
         #pulling = new Set();
         #wakeOrigins = new Set();
         #wakeRecipients = new Set();
@@ -292,11 +315,15 @@ export function createSyncDurableObject(config) {
         constructor(ctx, env) {
             super(ctx, env);
             const recordRowsWritten = (rows) => {
+                this.#sqlBilling.rowsWritten += rows;
                 if (this.#recordingIngestBillable)
                     this.#ingestBreaker.recordBillable(rows);
             };
-            this.#engineDb = new SqlStorageSyncDb(ctx.storage.sql, recordRowsWritten);
-            this.#directSql = new SqlStorageDirect(ctx.storage.sql, recordRowsWritten);
+            const recordRowsRead = (rows) => {
+                this.#sqlBilling.rowsRead += rows;
+            };
+            this.#engineDb = new SqlStorageSyncDb(ctx.storage.sql, recordRowsWritten, recordRowsRead);
+            this.#directSql = new SqlStorageDirect(ctx.storage.sql, recordRowsWritten, recordRowsRead);
             this.#mutatorSql = new SqlStorageMutatorTransaction(this.#directSql, (ast, format) => this.#wasm(() => compileQuery(ast, format)), config.transactionQueryBudget);
             const database = {
                 dialect: 'sqlite',
@@ -311,7 +338,16 @@ export function createSyncDurableObject(config) {
                             }
                             return this.#mutatorSql.exec(sql, params, metadata);
                         },
-                        query: (sql, params) => this.#mutatorSql.query(sql, params),
+                        query: (sql, params) => {
+                            // exact helper statements use sqlite returning so the executor
+                            // can prove the physical primary keys that changed. Keep the
+                            // host's pre-commit fault boundary after those writes too.
+                            if (/\b(?:INSERT|UPDATE|DELETE|REPLACE)\b/i.test(sql) &&
+                                /\bRETURNING\b/i.test(sql)) {
+                                applicationWrite = true;
+                            }
+                            return this.#mutatorSql.query(sql, params);
+                        },
                         queryAst: (ast, format, queryName) => this.#mutatorSql.queryAst(ast, format, queryName),
                     };
                     const value = await work(tx);
@@ -344,19 +380,35 @@ export function createSyncDurableObject(config) {
                 : null;
             ctx.blockConcurrencyWhile(async () => {
                 ctx.storage.transactionSync(() => {
-                    config.initialize(this.#directSql);
                     this.#directSql.exec(`CREATE TABLE IF NOT EXISTS _zsync_host_control (
             key TEXT PRIMARY KEY,
             value TEXT NOT NULL
           )`);
-                    this.#directSql.exec("INSERT OR IGNORE INTO _zsync_host_control (key, value) VALUES ('writerEnabled', '1')");
+                    // one durable fingerprint gates the whole schema pass. hibernation
+                    // reconstructs this object every few idle minutes, and re-running
+                    // consumer DDL plus both engine inits against an already-current
+                    // database costs ~1.5k billable reads per wake. everything the pass
+                    // depends on is in the fingerprint, so a build that changes any DDL
+                    // surface re-runs it exactly once per namespace.
+                    const initFingerprint = JSON.stringify([
+                        config.hostVersion,
+                        this.#wasm(() => engine_schema_revision()),
+                        config.schema,
+                        config.initialize.toString(),
+                    ]);
+                    this.#initSkipped = this.#controlGet('initFingerprint') === initFingerprint;
+                    if (!this.#initSkipped) {
+                        config.initialize(this.#directSql);
+                        this.#directSql.exec("INSERT OR IGNORE INTO _zsync_host_control (key, value) VALUES ('writerEnabled', '1')");
+                        this.#wasm(() => engine_init_schema(this.#engineDb, config.schema));
+                        this.#wasm(() => engine_init_query_schema(this.#engineDb));
+                        this.#controlSet('initFingerprint', initFingerprint);
+                    }
                     const ingestBreakerReason = this.#controlGet('ingestBreakerReason');
                     if (ingestBreakerReason === 'ingestBudgetExceeded' ||
                         ingestBreakerReason === 'ingestCursorStalled') {
                         this.#ingestBreaker.restore(ingestBreakerReason, Number(this.#controlGet('ingestBreakerRetryAt')), Number(this.#controlGet('ingestBreakerTrips')));
                     }
-                    this.#wasm(() => engine_init_schema(this.#engineDb, config.schema));
-                    this.#wasm(() => engine_init_query_schema(this.#engineDb));
                 });
             });
         }
@@ -378,6 +430,7 @@ export function createSyncDurableObject(config) {
                 this.#bootID = crypto.randomUUID();
                 this.#hibernations++;
                 this.#counters = freshCounters();
+                this.#sqlBilling = { rowsRead: 0, rowsWritten: 0 };
                 this.#pulling.clear();
                 this.#wakeOrigins.clear();
                 this.#wakeRecipients.clear();
@@ -402,8 +455,12 @@ export function createSyncDurableObject(config) {
             return row?.value ?? null;
         }
         #controlSet(key, value) {
+            // the WHERE guard makes a same-value set free: upstreamPath arrives on
+            // every forwarded request, and an unguarded upsert billed one row
+            // written per request for a value that almost never changes.
             this.#directSql.exec('INSERT INTO _zsync_host_control (key, value) VALUES (?, ?) ' +
-                'ON CONFLICT(key) DO UPDATE SET value = excluded.value', [key, value]);
+                'ON CONFLICT(key) DO UPDATE SET value = excluded.value ' +
+                'WHERE value <> excluded.value', [key, value]);
         }
         #controlDelete(...keys) {
             if (keys.length === 0)
@@ -1106,8 +1163,7 @@ export function createSyncDurableObject(config) {
                     return json({ pushResponse: delegatedResponse });
                 }
                 catch (error) {
-                    const status = statusOf(error);
-                    return json(errorBody(error), status);
+                    return errorResponse(error);
                 }
             }
             try {
@@ -1203,7 +1259,7 @@ export function createSyncDurableObject(config) {
                     totalMs: performance.now() - started,
                     resetReason: null,
                 });
-                return json({ error: errorMessage(error) }, status);
+                return errorResponse(error);
             }
         }
         // The hub for this incarnation, built on first use. Null unless the
@@ -1328,12 +1384,15 @@ export function createSyncDurableObject(config) {
         #admin(route, request, upstreamPath) {
             if (route === '/admin/health')
                 return json({ ok: true });
+            if (route === '/admin/sql-billing')
+                return json({ ...this.#sqlBilling });
             if (route === '/admin/upstream-write-budget' && request.method === 'GET')
                 return this.#upstreamWriteBudgetStatus();
             if (route === '/admin/status') {
                 const heap = performance.memory;
                 return this.ctx.storage.getAlarm().then((upstreamAlarmAt) => json({
                     bootID: this.#bootID,
+                    initSkipped: this.#initSkipped,
                     idleTeardownMs,
                     hibernations: this.#hibernations,
                     databaseSizeBytes: this.ctx.storage.sql.databaseSize,
@@ -1345,6 +1404,7 @@ export function createSyncDurableObject(config) {
                     heapTotalBytes: heap?.totalJSHeapSize ?? null,
                     heapLimitBytes: heap?.jsHeapSizeLimit ?? null,
                     engine: this.#engineStateBestEffort(),
+                    sqlBillingSinceBoot: this.#sqlBilling,
                     counters: this.#counters,
                     ingestBreaker: this.#ingestBreaker.status(),
                 }));
@@ -1391,7 +1451,7 @@ export function createSyncDurableObject(config) {
                         });
                     }
                     catch (error) {
-                        return json(errorBody(error), statusOf(error));
+                        return errorResponse(error);
                     }
                 })();
             }
@@ -1486,7 +1546,7 @@ export function createSyncDurableObject(config) {
                     return json({ ok: true, applied });
                 }
                 catch (error) {
-                    return json(errorBody(error), statusOf(error));
+                    return errorResponse(error);
                 }
             }
             if ((route === '/pull' || route === '/push') && request.method === 'POST') {
@@ -1495,14 +1555,14 @@ export function createSyncDurableObject(config) {
                     forwarded = await forwardedSyncRequest(request);
                 }
                 catch (error) {
-                    return json(errorBody(error), statusOf(error));
+                    return errorResponse(error);
                 }
                 // pull and push both establish the upstream schema and snapshot barrier.
                 try {
                     await this.#ingest(upstreamPath);
                 }
                 catch (error) {
-                    return json(errorBody(error), statusOf(error));
+                    return errorResponse(error);
                 }
                 if (route === '/pull') {
                     return this.#pull(forwarded.request, forwarded.claims, namespace);

package/dist/sql-storage-adapter.d.ts

@@ -27,8 +27,9 @@ export declare function decodeSqlParams(value: unknown): unknown[];
 export declare class SqlStorageSyncDb implements JsSyncDb {
     private readonly sql;
     private readonly recordRowsWritten;
+    private readonly recordRowsRead;
     readonly stats: AdapterStats;
-    constructor(sql: SqlStorage, recordRowsWritten?: (rows: number) => void);
+    constructor(sql: SqlStorage, recordRowsWritten?: (rows: number) => void, recordRowsRead?: (rows: number) => void);
     resetStats(): void;
     exec(sql: string, params: WireValue[]): void;
     query(sql: string, params: WireValue[]): WireRow[];
@@ -37,7 +38,8 @@ export declare class SqlStorageSyncDb implements JsSyncDb {
 export declare class SqlStorageDirect implements SyncSql {
     private readonly sql;
     private readonly recordRowsWritten;
-    constructor(sql: SqlStorage, recordRowsWritten?: (rows: number) => void);
+    private readonly recordRowsRead;
+    constructor(sql: SqlStorage, recordRowsWritten?: (rows: number) => void, recordRowsRead?: (rows: number) => void);
     exec(sql: string, params?: readonly unknown[], _metadata?: SqlStatementMetadata): ExecResult;
     query<Row extends Record<string, unknown> = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Row[];
 }

package/dist/sql-storage-adapter.js

@@ -98,10 +98,12 @@ function encodeResult(value) {
 export class SqlStorageSyncDb {
     sql;
     recordRowsWritten;
+    recordRowsRead;
     stats = { execCalls: 0, queryCalls: 0, sqlMs: 0 };
-    constructor(sql, recordRowsWritten = () => { }) {
+    constructor(sql, recordRowsWritten = () => { }, recordRowsRead = () => { }) {
         this.sql = sql;
         this.recordRowsWritten = recordRowsWritten;
+        this.recordRowsRead = recordRowsRead;
     }
     resetStats() {
         this.stats.execCalls = 0;
@@ -111,14 +113,14 @@ export class SqlStorageSyncDb {
     exec(sql, params) {
         assertHostSql(sql);
         const start = performance.now();
-        trackBillableCursorRows(this.sql.exec(sql, ...params.map((value) => decodeBinding(value))), this.recordRowsWritten);
+        trackBillableCursorRows(this.sql.exec(sql, ...params.map((value) => decodeBinding(value))), this.recordRowsWritten, this.recordRowsRead);
         this.stats.execCalls++;
         this.stats.sqlMs += performance.now() - start;
     }
     query(sql, params) {
         assertHostSql(sql);
         const start = performance.now();
-        const cursor = trackBillableCursorRows(this.sql.exec(sql, ...params.map((value) => decodeBinding(value))), this.recordRowsWritten);
+        const cursor = trackBillableCursorRows(this.sql.exec(sql, ...params.map((value) => decodeBinding(value))), this.recordRowsWritten, this.recordRowsRead);
         const columns = [...cursor.columnNames];
         // A SqlStorage cursor must be fully consumed before any await. Returning a
         // materialized array here makes that property structural.
@@ -135,19 +137,21 @@ export class SqlStorageSyncDb {
 export class SqlStorageDirect {
     sql;
     recordRowsWritten;
-    constructor(sql, recordRowsWritten = () => { }) {
+    recordRowsRead;
+    constructor(sql, recordRowsWritten = () => { }, recordRowsRead = () => { }) {
         this.sql = sql;
         this.recordRowsWritten = recordRowsWritten;
+        this.recordRowsRead = recordRowsRead;
     }
     exec(sql, params = [], _metadata) {
         assertHostSql(sql);
-        trackBillableCursorRows(this.sql.exec(sql, ...params), this.recordRowsWritten).toArray();
-        const changes = Number(this.sql.exec('SELECT changes() AS changes').one()?.changes ?? 0);
+        trackBillableCursorRows(this.sql.exec(sql, ...params), this.recordRowsWritten, this.recordRowsRead).toArray();
+        const changes = Number(trackBillableCursorRows(this.sql.exec('SELECT changes() AS changes'), this.recordRowsWritten, this.recordRowsRead).one()?.changes ?? 0);
         return { changes };
     }
     query(sql, params = []) {
         assertHostSql(sql);
-        return trackBillableCursorRows(this.sql.exec(sql, ...params), this.recordRowsWritten).toArray();
+        return trackBillableCursorRows(this.sql.exec(sql, ...params), this.recordRowsWritten, this.recordRowsRead).toArray();
     }
 }
 /**

package/dist/wasm.d.ts

@@ -18,5 +18,6 @@ export declare const engine_prune: (db: any, retain_changes: string) => void;
 export declare const engine_push_validate: (body: any) => any;
 export declare const engine_read_snapshot_progress: (db: any) => any;
 export declare const engine_record_app_error: (db: any, client_group_id: string, client_id: string, mutation_id: string, user_id: string) => void;
+export declare const engine_schema_revision: () => string;
 export declare const engine_state: (db: any) => any;
 export declare const engine_version: () => string;

package/dist/wasm.js

@@ -35,5 +35,6 @@ export const engine_prune = withWasm(generated.engine_prune);
 export const engine_push_validate = withWasm(generated.engine_push_validate);
 export const engine_read_snapshot_progress = withWasm(generated.engine_read_snapshot_progress);
 export const engine_record_app_error = withWasm(generated.engine_record_app_error);
+export const engine_schema_revision = withWasm(generated.engine_schema_revision);
 export const engine_state = withWasm(generated.engine_state);
 export const engine_version = withWasm(generated.engine_version);

package/dist/write-safeguards.d.ts

@@ -40,6 +40,7 @@ export declare class IngestCircuitBreaker {
     reopen(): void;
 }
 type BillableCursor = {
+    rowsRead?: number;
     rowsWritten?: number;
     next?: (...args: unknown[]) => unknown;
     one?: (...args: unknown[]) => unknown;
@@ -47,7 +48,7 @@ type BillableCursor = {
     raw?: (...args: unknown[]) => unknown;
     [Symbol.iterator]?: () => Iterator<unknown>;
 };
-export declare function trackBillableCursorRows<Cursor extends BillableCursor>(cursor: Cursor, record: (rows: number) => void): Cursor;
+export declare function trackBillableCursorRows<Cursor extends BillableCursor>(cursor: Cursor, recordWritten: (rows: number) => void, recordRead?: (rows: number) => void): Cursor;
 export declare function retryDelayMs(attempt: number, initialBackoffMs: number, maxBackoffMs: number): number;
 export declare function shouldRetryDelegatedPush(responseStatus: number | null, attempt: number, maxAttempts: number): boolean;
 export {};

package/dist/write-safeguards.js

@@ -122,17 +122,22 @@ export class IngestCircuitBreaker {
         this.recovered();
     }
 }
-export function trackBillableCursorRows(cursor, record) {
+export function trackBillableCursorRows(cursor, recordWritten, recordRead = () => { }) {
     if (!cursor || typeof cursor !== 'object')
         return cursor;
-    let accountedRows = 0;
+    let accountedWritten = 0;
+    let accountedRead = 0;
     const account = () => {
-        const current = Number(cursor.rowsWritten ?? 0);
-        if (!Number.isSafeInteger(current) || current <= accountedRows)
-            return;
-        const delta = current - accountedRows;
-        accountedRows = current;
-        record(delta);
+        const written = Number(cursor.rowsWritten ?? 0);
+        if (Number.isSafeInteger(written) && written > accountedWritten) {
+            recordWritten(written - accountedWritten);
+            accountedWritten = written;
+        }
+        const read = Number(cursor.rowsRead ?? 0);
+        if (Number.isSafeInteger(read) && read > accountedRead) {
+            recordRead(read - accountedRead);
+            accountedRead = read;
+        }
     };
     const wrapIterator = (iterator) => {
         const next = iterator.next.bind(iterator);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orez-sync-cf-host",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "Internal orez Cloudflare sync host. Do not import directly: consumers use orez-lite/cloudflare/sync.",
   "type": "module",
   "exports": {
@@ -58,7 +58,7 @@
     "test:large-data": "bun run build:dist && bun large-data-test.mjs"
   },
   "dependencies": {
-    "orez-sync-executor": "0.12.1"
+    "orez-sync-executor": "0.12.3"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "4.20260617.1",