@syncular/server 0.15.45 → 0.15.46

package/dist/d1-storage.js

@@ -41,12 +41,39 @@ var _a;
  * rather than a lock D1 does not expose.
  */
 import { decodeRow } from '@syncular/core';
+import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { asUint8Array, collectCommitWindowPage, deserializePushResult, serializePushResult, sqliteDdlStatements, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
+function toStoredReaction(record) {
+    return {
+        idempotencyKey: record.idempotency_key,
+        type: record.type,
+        version: record.version,
+        payload: JSON.parse(record.payload),
+        sourceClientId: record.source_client_id,
+        sourceClientCommitId: record.source_client_commit_id,
+        sourceCommitSeq: record.source_commit_seq,
+        createdAtMs: record.created_at_ms,
+        maxAttempts: record.max_attempts,
+        status: record.status,
+        attempts: record.attempts,
+        availableAtMs: record.available_at_ms,
+        ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
+        ...(record.lease_expires_at_ms !== null
+            ? { leaseExpiresAtMs: record.lease_expires_at_ms }
+            : {}),
+        ...(record.completed_at_ms !== null
+            ? { completedAtMs: record.completed_at_ms }
+            : {}),
+        ...(record.last_failure !== null
+            ? { lastFailure: JSON.parse(record.last_failure) }
+            : {}),
+    };
+}
 function relationalValuesEqual(left, right) {
     if (left instanceof Uint8Array && right instanceof Uint8Array) {
         return (left.length === right.length &&
@@ -376,6 +403,28 @@ class D1Transaction {
         this.#assertOpen();
         this.#buffer_('INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)', [this.#partition, clientId, clientCommitId, serializePushResult(result)]);
     }
+    async enqueueReactions(reactions) {
+        this.#assertOpen();
+        for (const reaction of reactions) {
+            this.#buffer_(`INSERT INTO sync_reactions(
+           partition, idempotency_key, type, version, payload,
+           source_client_id, source_client_commit_id, source_commit_seq,
+           created_at_ms, available_at_ms, status, attempts, max_attempts
+         ) VALUES (?,?,?,?,?,?,?,?,?,?,'pending',0,?)`, [
+                this.#partition,
+                reaction.idempotencyKey,
+                reaction.type,
+                reaction.version,
+                JSON.stringify(reaction.payload),
+                reaction.sourceClientId,
+                reaction.sourceClientCommitId,
+                reaction.sourceCommitSeq,
+                reaction.createdAtMs,
+                reaction.createdAtMs,
+                reaction.maxAttempts,
+            ]);
+        }
+    }
     async commit() {
         this.#assertOpen();
         if (this.#buffer.length === 0) {
@@ -555,6 +604,41 @@ export class D1ServerStorage {
             .first();
         return row?.max_commit_seq ?? 0;
     }
+    async queryAuthoritative(partition, query) {
+        if (this.#tables === undefined) {
+            throw new Error('ensureSchema(schema) must run before registered queries');
+        }
+        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.sql, query.params, query.tables, this.#tables), partition);
+        const results = await this.#db.batch([
+            this.#db.prepare(prepared.sql).bind(...prepared.params),
+            this.#db
+                .prepare('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
+                .bind(partition),
+        ]);
+        const rowsResult = results[0];
+        const cursorResult = results[1];
+        if (typeof rowsResult !== 'object' ||
+            rowsResult === null ||
+            !('results' in rowsResult) ||
+            !Array.isArray(rowsResult.results) ||
+            typeof cursorResult !== 'object' ||
+            cursorResult === null ||
+            !('results' in cursorResult) ||
+            !Array.isArray(cursorResult.results)) {
+            throw new Error('D1 registered query returned an invalid batch result');
+        }
+        const cursor = cursorResult.results[0];
+        const maxCommitSeq = typeof cursor === 'object' &&
+            cursor !== null &&
+            'max_commit_seq' in cursor &&
+            typeof cursor.max_commit_seq === 'number'
+            ? cursor.max_commit_seq
+            : 0;
+        return {
+            rows: rowsResult.results.filter((row) => typeof row === 'object' && row !== null),
+            maxCommitSeq,
+        };
+    }
     async getHorizonSeq(partition) {
         const row = await this.#db
             .prepare('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
@@ -614,6 +698,138 @@ export class D1ServerStorage {
             throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
         }
     }
+    async claimReactions(partition, query) {
+        if (query.types.length === 0 || query.limit <= 0)
+            return [];
+        if (query.types.length + 7 > D1_MAX_BIND_PARAMS) {
+            throw new Error('D1 reaction claim exceeds the bound-parameter limit');
+        }
+        const typeParams = query.types.map(() => '?').join(',');
+        const { results } = await this.#db
+            .prepare(`UPDATE sync_reactions
+            SET status='leased', attempts=attempts+1,
+                lease_owner=?, lease_expires_at_ms=?, completed_at_ms=NULL
+          WHERE (partition, idempotency_key) IN (
+            SELECT partition, idempotency_key
+              FROM sync_reactions
+             WHERE partition=? AND type IN (${typeParams})
+               AND ((status='pending' AND available_at_ms<=?)
+                 OR (status='leased' AND lease_expires_at_ms<=?))
+             ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
+                           ELSE available_at_ms END,
+                      created_at_ms, idempotency_key
+             LIMIT ?
+          )
+        RETURNING *`)
+            .bind(query.leaseOwner, Math.min(Number.MAX_SAFE_INTEGER, query.nowMs + query.leaseDurationMs), partition, ...query.types, query.nowMs, query.nowMs, query.limit)
+            .all();
+        return results
+            .map(toStoredReaction)
+            .sort((a, b) => a.createdAtMs - b.createdAtMs ||
+            a.idempotencyKey.localeCompare(b.idempotencyKey));
+    }
+    async completeReaction(partition, idempotencyKey, leaseOwner, completedAtMs) {
+        const record = await this.#db
+            .prepare(`UPDATE sync_reactions
+            SET status='completed', completed_at_ms=?,
+                lease_owner=NULL, lease_expires_at_ms=NULL
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?
+        RETURNING idempotency_key`)
+            .bind(completedAtMs, partition, idempotencyKey, leaseOwner)
+            .first();
+        return record !== null;
+    }
+    async extendReactionLease(partition, idempotencyKey, leaseOwner, leaseExpiresAtMs) {
+        const record = await this.#db
+            .prepare(`UPDATE sync_reactions SET lease_expires_at_ms=?
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?
+        RETURNING idempotency_key`)
+            .bind(leaseExpiresAtMs, partition, idempotencyKey, leaseOwner)
+            .first();
+        return record !== null;
+    }
+    async failReaction(partition, idempotencyKey, update) {
+        const record = await this.#db
+            .prepare(`UPDATE sync_reactions
+            SET status=?, available_at_ms=?, last_failure=?,
+                lease_owner=NULL, lease_expires_at_ms=NULL
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?
+        RETURNING idempotency_key`)
+            .bind(update.retryAtMs === undefined ? 'dead-letter' : 'pending', update.retryAtMs ?? update.failure.atMs, JSON.stringify(update.failure), partition, idempotencyKey, update.leaseOwner)
+            .first();
+        return record !== null;
+    }
+    async retryReaction(partition, idempotencyKey, nowMs) {
+        const record = await this.#db
+            .prepare(`UPDATE sync_reactions
+            SET status='pending', attempts=0, available_at_ms=?,
+                last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
+                completed_at_ms=NULL
+          WHERE partition=? AND idempotency_key=? AND status='dead-letter'
+        RETURNING idempotency_key`)
+            .bind(nowMs, partition, idempotencyKey)
+            .first();
+        return record !== null;
+    }
+    async getReaction(partition, idempotencyKey) {
+        const record = await this.#db
+            .prepare('SELECT * FROM sync_reactions WHERE partition=? AND idempotency_key=?')
+            .bind(partition, idempotencyKey)
+            .first();
+        return record === null ? undefined : toStoredReaction(record);
+    }
+    async listReactions(partition, query) {
+        const where = ['partition=?'];
+        const params = [partition];
+        if (query.statuses !== undefined && query.statuses.length > 0) {
+            where.push(`status IN (${query.statuses.map(() => '?').join(',')})`);
+            params.push(...query.statuses);
+        }
+        if (query.types !== undefined && query.types.length > 0) {
+            where.push(`type IN (${query.types.map(() => '?').join(',')})`);
+            params.push(...query.types);
+        }
+        if (params.length + 1 > D1_MAX_BIND_PARAMS) {
+            throw new Error('D1 reaction list exceeds the bound-parameter limit');
+        }
+        params.push(query.limit);
+        const { results } = await this.#db
+            .prepare(`SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
+          ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT ?`)
+            .bind(...params)
+            .all();
+        return results.map(toStoredReaction);
+    }
+    async pruneReactions(partition, query) {
+        if (query.limit <= 0)
+            return { completed: 0, deadLetter: 0 };
+        const { results } = await this.#db
+            .prepare(`DELETE FROM sync_reactions
+          WHERE partition=? AND idempotency_key IN (
+            SELECT idempotency_key FROM sync_reactions
+             WHERE partition=?
+               AND ((status='completed' AND completed_at_ms IS NOT NULL
+                     AND completed_at_ms<?)
+                 OR (status='dead-letter' AND available_at_ms<?))
+             ORDER BY CASE WHEN status='completed' THEN completed_at_ms
+                           ELSE available_at_ms END,
+                      idempotency_key
+             LIMIT ?
+          )
+            AND ((status='completed' AND completed_at_ms IS NOT NULL
+                  AND completed_at_ms<?)
+              OR (status='dead-letter' AND available_at_ms<?))
+        RETURNING status`)
+            .bind(partition, partition, query.completedBeforeMs, query.deadLetterBeforeMs, query.limit, query.completedBeforeMs, query.deadLetterBeforeMs)
+            .all();
+        return {
+            completed: results.filter((row) => row.status === 'completed').length,
+            deadLetter: results.filter((row) => row.status === 'dead-letter').length,
+        };
+    }
     async readCommitWindow(partition, query) {
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];

package/dist/errors.d.ts

@@ -12,7 +12,7 @@ export interface ErrorCatalogEntry {
     readonly recommendedAction: string;
     readonly httpStatus: number;
 }
-/** The §10.2 wire catalog (21 sync.* + 4 blob.* codes), keyed by stable code. */
+/** The §10.2 wire catalog, keyed by stable code. */
 export declare const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>>;
 export declare class SyncError extends Error {
     readonly name = "SyncError";

package/dist/errors.js

@@ -6,8 +6,50 @@
  * `recommendedAction`) plus an HTTP status for transport adapters. The
  * catalog is closed: creating a `SyncError` with an unknown code throws.
  */
-/** The §10.2 wire catalog (21 sync.* + 4 blob.* codes), keyed by stable code. */
+/** The §10.2 wire catalog, keyed by stable code. */
 export const ERROR_CATALOG = {
+    'operation.unknown': {
+        category: 'not-found',
+        retryable: false,
+        recommendedAction: 'regenerateClient',
+        httpStatus: 404,
+    },
+    'operation.forbidden': {
+        category: 'forbidden',
+        retryable: false,
+        recommendedAction: 'checkPermissions',
+        httpStatus: 403,
+    },
+    'operation.invalid_request': {
+        category: 'invalid-request',
+        retryable: false,
+        recommendedAction: 'fixRequest',
+        httpStatus: 400,
+    },
+    'operation.result_too_large': {
+        category: 'invalid-request',
+        retryable: false,
+        recommendedAction: 'fixRequest',
+        httpStatus: 400,
+    },
+    'operation.storage_unsupported': {
+        category: 'internal',
+        retryable: false,
+        recommendedAction: 'inspectServer',
+        httpStatus: 500,
+    },
+    'operation.query_failed': {
+        category: 'internal',
+        retryable: false,
+        recommendedAction: 'inspectServer',
+        httpStatus: 500,
+    },
+    'operation.execution_failed': {
+        category: 'internal',
+        retryable: false,
+        recommendedAction: 'inspectServer',
+        httpStatus: 500,
+    },
     'sync.auth_required': {
         category: 'auth-required',
         retryable: true,

package/dist/events.d.ts

@@ -1,6 +1,6 @@
 /**
- * Structured server events — the one operational seam (host surface, not
- * wire protocol; SPEC.md is untouched by this module).
+ * Structured server events — the one operational seam (host surface, outside
+ * the wire protocol).
  *
  * Design rules:
  * - Every event is a flat, JSON-able object with a stable `type` string:
@@ -75,6 +75,55 @@ export interface PushConflictedEvent extends PushEventBase {
     readonly recordedAtMs?: number;
     readonly cacheIdentity?: string;
 }
+/** A planned reaction committed atomically with its accepted source commit. */
+export interface ReactionQueuedEvent {
+    readonly type: 'reaction.queued';
+    readonly atMs: number;
+    readonly partition: string;
+    readonly actorId: string;
+    readonly clientId: string;
+    readonly clientCommitId: string;
+    readonly commitSeq: number;
+    readonly idempotencyKey: string;
+    readonly reactionType: string;
+    readonly version: number;
+}
+interface ReactionDeliveryEventBase {
+    readonly atMs: number;
+    readonly partition: string;
+    readonly workerId: string;
+    readonly idempotencyKey: string;
+    readonly reactionType: string;
+    readonly version: number;
+    readonly attempt: number;
+}
+export interface ReactionStartedEvent extends ReactionDeliveryEventBase {
+    readonly type: 'reaction.started';
+}
+export interface ReactionRetriedEvent extends ReactionDeliveryEventBase {
+    readonly type: 'reaction.retried';
+    readonly nextAttemptAtMs: number;
+    readonly errorCode: string;
+}
+export interface ReactionCompletedEvent extends ReactionDeliveryEventBase {
+    readonly type: 'reaction.completed';
+}
+export interface ReactionDeadLetteredEvent extends ReactionDeliveryEventBase {
+    readonly type: 'reaction.dead_lettered';
+    readonly errorCode: string;
+}
+/** One bounded terminal-reaction retention pass. */
+export interface ReactionPruneCompletedEvent {
+    readonly type: 'reaction.prune_completed';
+    readonly atMs: number;
+    readonly partition: string;
+    readonly completedBeforeMs: number;
+    readonly deadLetterBeforeMs: number;
+    readonly limit: number;
+    readonly removedCompleted: number;
+    readonly removedDeadLetter: number;
+    readonly mayHaveMore: boolean;
+}
 /** One emitted segment within a pull subscription section. */
 export interface PullSegmentSummary {
     readonly mediaType: 'rows' | 'sqlite';
@@ -221,7 +270,7 @@ export interface LeaseRevokedEvent {
     readonly partition: string;
     readonly leaseId: string;
 }
-export type SyncularServerEvent = RequestHandledEvent | PushAppliedEvent | PushRejectedEvent | PushConflictedEvent | PullServedEvent | SegmentDownloadedEvent | BlobUploadedEvent | BlobDownloadedEvent | BlobSweptEvent | RealtimeOpenedEvent | RealtimeClosedEvent | RealtimeDeltaEvent | RealtimeWakeEvent | PruneCompletedEvent | ScopesResolveFailedEvent | LeaseIssuedEvent | LeaseRevokedEvent;
+export type SyncularServerEvent = RequestHandledEvent | PushAppliedEvent | PushRejectedEvent | PushConflictedEvent | ReactionQueuedEvent | ReactionStartedEvent | ReactionRetriedEvent | ReactionCompletedEvent | ReactionDeadLetteredEvent | ReactionPruneCompletedEvent | PullServedEvent | SegmentDownloadedEvent | BlobUploadedEvent | BlobDownloadedEvent | BlobSweptEvent | RealtimeOpenedEvent | RealtimeClosedEvent | RealtimeDeltaEvent | RealtimeWakeEvent | PruneCompletedEvent | ScopesResolveFailedEvent | LeaseIssuedEvent | LeaseRevokedEvent;
 /**
  * The seam. Optional on the server config — when absent, no event object
  * is ever built. Implementations receive every event synchronously and

package/dist/handler.js

@@ -10,7 +10,7 @@
  * frame (§1.6).
  */
 import { DecodeError, decodeMessage, } from '@syncular/core';
-import { clockOf, limitsOf, RESOLVER_OUTAGE } from './context.js';
+import { clockOf, limitsOf, REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, } from './context.js';
 import { SyncError, syncError } from './errors.js';
 import { emitEvent, } from './events.js';
 import { END_FRAME_BYTES, encodeResponseFrame, RESPONSE_ENVELOPE_HEADER, } from './frame-bytes.js';
@@ -125,6 +125,9 @@ async function planRequest(request, ctx, schema) {
             leaseToEmit: undefined,
         };
     }
+    if (header.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
+        throw syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)');
+    }
     // §1.5: a clientId already bound to a different actor is rejected.
     const record = await ctx.storage.getClientRecord(ctx.partition, header.clientId);
     if (record !== undefined && record.actorId !== ctx.actorId) {

package/dist/index.d.ts

@@ -8,6 +8,7 @@
  * handler (§5.5), and signed-URL token issuance/verification (§5.4).
  */
 export * from './admin.js';
+export * from './authoritative-query.js';
 export * from './blob-handlers.js';
 export * from './blob-store.js';
 export * from './content-encoding.js';
@@ -20,6 +21,8 @@ export * from './events-ring.js';
 export * from './frame-bytes.js';
 export * from './handler.js';
 export * from './lease-store.js';
+export * from './operations.js';
+export * from './operations-realtime.js';
 export * from './pg-executor.js';
 export * from './postgres-fanout.js';
 export * from './postgres-storage.js';
@@ -27,6 +30,7 @@ export * from './prune.js';
 export * from './pull.js';
 export * from './push.js';
 export * from './readiness.js';
+export { DEFAULT_REACTION_INITIAL_BACKOFF_MS, DEFAULT_REACTION_LEASE_MS, DEFAULT_REACTION_MAX_ATTEMPTS, DEFAULT_REACTION_MAX_BACKOFF_MS, DEFAULT_REACTION_RETENTION, MAX_REACTION_FAILURE_DETAILS_BYTES, MAX_REACTION_PAYLOAD_BYTES, MAX_REACTIONS_PER_COMMIT, PermanentReactionError, pruneReactions, ReactionRunner, reactionIdempotencyKey, retryDeadLetterReaction, RetryableReactionError, type PlannedReaction, type PruneReactionsOptions, type ReactionHandler, type ReactionHandlerInput, type ReactionHandlers, type ReactionPlan, type ReactionPlanner, type ReactionPlannerInput, type ReactionPruneResult, type ReactionRetentionPolicy, type ReactionRunnerOptions, type ReactionRunResult, type ReactionTypeMap, } from './reactions.js';
 export * from './realtime.js';
 export * from './relational-rows.js';
 export * from './s3-blob-store.js';

package/dist/index.js

@@ -8,6 +8,7 @@
  * handler (§5.5), and signed-URL token issuance/verification (§5.4).
  */
 export * from './admin.js';
+export * from './authoritative-query.js';
 export * from './blob-handlers.js';
 export * from './blob-store.js';
 export * from './content-encoding.js';
@@ -20,6 +21,8 @@ export * from './events-ring.js';
 export * from './frame-bytes.js';
 export * from './handler.js';
 export * from './lease-store.js';
+export * from './operations.js';
+export * from './operations-realtime.js';
 // The `PgExecutor` seam + Postgres storage/fanout are driver-agnostic (zero
 // runtime deps). Concrete driver adapters (pglite for tests; Bun.sql /
 // node-postgres for production, documented in the README) live in separate
@@ -31,6 +34,7 @@ export * from './prune.js';
 export * from './pull.js';
 export * from './push.js';
 export * from './readiness.js';
+export { DEFAULT_REACTION_INITIAL_BACKOFF_MS, DEFAULT_REACTION_LEASE_MS, DEFAULT_REACTION_MAX_ATTEMPTS, DEFAULT_REACTION_MAX_BACKOFF_MS, DEFAULT_REACTION_RETENTION, MAX_REACTION_FAILURE_DETAILS_BYTES, MAX_REACTION_PAYLOAD_BYTES, MAX_REACTIONS_PER_COMMIT, PermanentReactionError, pruneReactions, ReactionRunner, reactionIdempotencyKey, retryDeadLetterReaction, RetryableReactionError, } from './reactions.js';
 export * from './realtime.js';
 export * from './relational-rows.js';
 export * from './s3-blob-store.js';

package/dist/operations-realtime.d.ts

@@ -0,0 +1,16 @@
+import type { RealtimeNotifier, SyncRequestContext } from './context.js';
+import type { RemoteOperationRegistry } from './operations.js';
+import type { StoredCommit } from './storage.js';
+export interface RemoteOperationWatchSession {
+    receive(bytes: Uint8Array): Promise<void>;
+    close(): void;
+}
+/** In-memory invalidation hub. Every notification reruns affected watches. */
+export declare class RemoteOperationWatchHub implements RealtimeNotifier {
+    #private;
+    constructor(registry: RemoteOperationRegistry);
+    connect(ctx: SyncRequestContext, send: (bytes: Uint8Array) => void): RemoteOperationWatchSession;
+    notifyCommit(partition: string, commit: StoredCommit): void;
+}
+/** Fan one applied commit into sync deltas and registered query watches. */
+export declare function composeRealtimeNotifiers(...notifiers: readonly RealtimeNotifier[]): RealtimeNotifier;

package/dist/operations-realtime.js

@@ -0,0 +1,196 @@
+import { decodeRemoteOperationRealtimeMessage, encodeRemoteOperationRealtimeMessage, } from '@syncular/core';
+import { REMOTE_COMMAND_CLIENT_ID_PREFIX } from './context.js';
+import { SyncError, syncError } from './errors.js';
+class WatchSession {
+    #ctx;
+    #registry;
+    #send;
+    #closed;
+    #watches = new Map();
+    #isClosed = false;
+    get partition() {
+        return this.#ctx.partition;
+    }
+    constructor(ctx, registry, send, closed) {
+        this.#ctx = ctx;
+        this.#registry = registry;
+        this.#send = send;
+        this.#closed = closed;
+    }
+    async receive(bytes) {
+        if (this.#isClosed)
+            return;
+        let message;
+        try {
+            message = decodeRemoteOperationRealtimeMessage(bytes);
+            if (typeof message !== 'object' ||
+                message === null ||
+                message.revision !== 1 ||
+                (message.kind !== 'watch' && message.kind !== 'unwatch') ||
+                typeof message.watchId !== 'string' ||
+                message.watchId.length === 0) {
+                throw syncError('operation.invalid_request');
+            }
+            if (message.kind === 'watch') {
+                if (typeof message.clientId !== 'string' ||
+                    message.clientId.length === 0 ||
+                    typeof message.operationId !== 'string' ||
+                    message.operationId.length === 0) {
+                    throw syncError('operation.invalid_request');
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof SyncError)
+                throw error;
+            throw syncError('operation.invalid_request');
+        }
+        if (message.kind === 'unwatch') {
+            this.#watches.delete(message.watchId);
+            return;
+        }
+        if (this.#watches.has(message.watchId)) {
+            this.#sendError(message.watchId, syncError('operation.invalid_request', 'watchId is already active'));
+            return;
+        }
+        if (message.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
+            this.#sendError(message.watchId, syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)'));
+            return;
+        }
+        const clientRecord = await this.#ctx.storage.getClientRecord(this.#ctx.partition, message.clientId);
+        if (clientRecord !== undefined &&
+            clientRecord.actorId !== this.#ctx.actorId) {
+            this.#sendError(message.watchId, syncError('sync.invalid_client_id', 'clientId is bound to a different actor in this partition (§1.5)'));
+            return;
+        }
+        const operation = this.#registry.get(message.operationId);
+        if (operation === undefined || operation.kind !== 'query') {
+            this.#sendError(message.watchId, syncError('operation.unknown'));
+            return;
+        }
+        const state = {
+            watchId: message.watchId,
+            clientId: message.clientId,
+            operation,
+            params: message.params,
+            running: false,
+            dirty: false,
+        };
+        this.#watches.set(message.watchId, state);
+        await this.#refresh(state);
+    }
+    notify(tables) {
+        for (const state of this.#watches.values()) {
+            if (!state.operation.tables.some((table) => tables.has(table)))
+                continue;
+            if (state.running)
+                state.dirty = true;
+            else
+                void this.#refresh(state);
+        }
+    }
+    async #refresh(state) {
+        if (this.#isClosed || this.#watches.get(state.watchId) !== state)
+            return;
+        if (state.running) {
+            state.dirty = true;
+            return;
+        }
+        state.running = true;
+        try {
+            do {
+                state.dirty = false;
+                try {
+                    const response = await state.operation.run(this.#ctx, state.clientId, state.params);
+                    if (this.#isClosed || this.#watches.get(state.watchId) !== state) {
+                        return;
+                    }
+                    if (response.kind !== 'query') {
+                        throw syncError('operation.query_failed');
+                    }
+                    if (!this.#emit(encodeRemoteOperationRealtimeMessage({
+                        revision: 1,
+                        kind: 'snapshot',
+                        watchId: state.watchId,
+                        operationId: response.operationId,
+                        rows: response.rows,
+                        maxCommitSeq: response.maxCommitSeq,
+                    })))
+                        return;
+                }
+                catch (error) {
+                    if (this.#isClosed || this.#watches.get(state.watchId) !== state) {
+                        return;
+                    }
+                    this.#sendError(state.watchId, error instanceof SyncError
+                        ? error
+                        : syncError('operation.query_failed'));
+                }
+            } while (state.dirty &&
+                !this.#isClosed &&
+                this.#watches.get(state.watchId) === state);
+        }
+        finally {
+            state.running = false;
+        }
+    }
+    #sendError(watchId, error) {
+        this.#emit(encodeRemoteOperationRealtimeMessage({
+            revision: 1,
+            kind: 'watch_error',
+            watchId,
+            code: error.code,
+            message: error.message,
+            retryable: error.retryable,
+        }));
+    }
+    #emit(bytes) {
+        if (this.#isClosed)
+            return false;
+        try {
+            this.#send(bytes);
+            return true;
+        }
+        catch {
+            this.close();
+            return false;
+        }
+    }
+    close() {
+        if (this.#isClosed)
+            return;
+        this.#isClosed = true;
+        this.#watches.clear();
+        this.#closed();
+    }
+}
+/** In-memory invalidation hub. Every notification reruns affected watches. */
+export class RemoteOperationWatchHub {
+    #registry;
+    #sessions = new Set();
+    constructor(registry) {
+        this.#registry = registry;
+    }
+    connect(ctx, send) {
+        const session = new WatchSession(ctx, this.#registry, send, () => {
+            this.#sessions.delete(session);
+        });
+        this.#sessions.add(session);
+        return session;
+    }
+    notifyCommit(partition, commit) {
+        const tables = new Set(commit.changes.map((change) => change.table));
+        for (const session of this.#sessions) {
+            if (session.partition === partition)
+                session.notify(tables);
+        }
+    }
+}
+/** Fan one applied commit into sync deltas and registered query watches. */
+export function composeRealtimeNotifiers(...notifiers) {
+    return {
+        notifyCommit: async (partition, commit) => {
+            await Promise.all(notifiers.map((notifier) => notifier.notifyCommit(partition, commit)));
+        },
+    };
+}