@syncular/server 0.15.45 → 0.15.46

package/dist/reactions.js

@@ -0,0 +1,442 @@
+import { emitEvent } from './events.js';
+export const MAX_REACTIONS_PER_COMMIT = 100;
+export const MAX_REACTION_PAYLOAD_BYTES = 64 * 1024;
+export const MAX_REACTION_FAILURE_DETAILS_BYTES = 8 * 1024;
+export const DEFAULT_REACTION_MAX_ATTEMPTS = 10;
+export const DEFAULT_REACTION_LEASE_MS = 30_000;
+export const DEFAULT_REACTION_INITIAL_BACKOFF_MS = 1_000;
+export const DEFAULT_REACTION_MAX_BACKOFF_MS = 5 * 60_000;
+export const DEFAULT_REACTION_RETENTION = {
+    completedRetentionMs: 30 * 24 * 60 * 60 * 1000,
+    deadLetterRetentionMs: 90 * 24 * 60 * 60 * 1000,
+    batchSize: 1_000,
+};
+function normalizedJson(value, path, depth = 0) {
+    if (depth > 16)
+        throw new Error(`${path} exceeds the maximum JSON depth`);
+    if (value === null ||
+        typeof value === 'boolean' ||
+        typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`${path} must be finite`);
+        return value;
+    }
+    if (Array.isArray(value)) {
+        for (const key of Reflect.ownKeys(value)) {
+            if (key === 'length')
+                continue;
+            if (typeof key !== 'string' ||
+                !/^(?:0|[1-9][0-9]*)$/.test(key) ||
+                Number(key) >= value.length) {
+                throw new Error(`${path} arrays cannot carry extra properties`);
+            }
+        }
+        const output = [];
+        for (let index = 0; index < value.length; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (descriptor === undefined || !('value' in descriptor)) {
+                throw new Error(`${path}[${index}] must be a plain JSON value`);
+            }
+            output.push(normalizedJson(descriptor.value, `${path}[${index}]`, depth + 1));
+        }
+        return output;
+    }
+    if (typeof value !== 'object') {
+        throw new Error(`${path} must contain only JSON values`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error(`${path} must contain only plain JSON objects`);
+    }
+    const output = {};
+    const entries = [];
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== 'string') {
+            throw new Error(`${path} cannot contain symbol keys`);
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined ||
+            !descriptor.enumerable ||
+            !('value' in descriptor)) {
+            throw new Error(`${path}.${key} must be an enumerable data property`);
+        }
+        entries.push([key, descriptor.value]);
+    }
+    for (const [key, entry] of entries.sort(([left], [right]) => left.localeCompare(right))) {
+        Object.defineProperty(output, key, {
+            value: normalizedJson(entry, `${path}.${key}`, depth + 1),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return output;
+}
+function boundedJson(value, path, maxBytes) {
+    const normalized = normalizedJson(value, path);
+    if (new TextEncoder().encode(JSON.stringify(normalized)).byteLength > maxBytes) {
+        throw new Error(`${path} exceeds ${maxBytes} persisted bytes`);
+    }
+    return normalized;
+}
+function assertName(value, field, maxBytes) {
+    if (!/^[A-Za-z][A-Za-z0-9._:-]*$/.test(value) ||
+        new TextEncoder().encode(value).byteLength > maxBytes) {
+        throw new Error(`${field} must be a code-like string no longer than ${maxBytes} bytes`);
+    }
+}
+/** Stable handler idempotency key for one planned item in a client commit. */
+export function reactionIdempotencyKey(partition, clientId, clientCommitId, plannerKey) {
+    return JSON.stringify([partition, clientId, clientCommitId, plannerKey]);
+}
+/** Internal push seam, exported for focused planner tests and custom hosts. */
+export async function prepareReactions(planner, input) {
+    const planned = await planner(input);
+    if (!Array.isArray(planned)) {
+        throw new Error('reaction planner must return an array');
+    }
+    if (planned.length > MAX_REACTIONS_PER_COMMIT) {
+        throw new Error(`reaction planner returned more than ${MAX_REACTIONS_PER_COMMIT} records`);
+    }
+    const keys = new Set();
+    return planned.map((reaction, index) => {
+        assertName(reaction.type, `reaction[${index}].type`, 128);
+        if (reaction.key.length === 0 ||
+            new TextEncoder().encode(reaction.key).byteLength > 256) {
+            throw new Error(`reaction[${index}].key must be non-empty and no longer than 256 bytes`);
+        }
+        if (keys.has(reaction.key)) {
+            throw new Error(`reaction planner returned duplicate key at index ${index}`);
+        }
+        keys.add(reaction.key);
+        if (!Number.isSafeInteger(reaction.version) ||
+            reaction.version < 1 ||
+            reaction.version > 2_147_483_647) {
+            throw new Error(`reaction[${index}].version must be a positive int32`);
+        }
+        const maxAttempts = reaction.maxAttempts ?? DEFAULT_REACTION_MAX_ATTEMPTS;
+        if (!Number.isSafeInteger(maxAttempts) ||
+            maxAttempts < 1 ||
+            maxAttempts > 100) {
+            throw new Error(`reaction[${index}].maxAttempts must be from 1 through 100`);
+        }
+        return {
+            idempotencyKey: reactionIdempotencyKey(input.partition, input.clientId, input.clientCommitId, reaction.key),
+            type: reaction.type,
+            version: reaction.version,
+            payload: boundedJson(reaction.payload, `reaction[${index}].payload`, MAX_REACTION_PAYLOAD_BYTES),
+            maxAttempts,
+        };
+    });
+}
+class ReactionDeliveryError extends Error {
+    code;
+    details;
+    constructor(name, code, details) {
+        super(code);
+        this.name = name;
+        assertName(code, `${name}.code`, 128);
+        this.code = code;
+        if (details !== undefined) {
+            this.details = boundedJson(details, `${name}.details`, MAX_REACTION_FAILURE_DETAILS_BYTES);
+        }
+    }
+}
+/** A handler failure that should be retried until its attempt limit. */
+export class RetryableReactionError extends ReactionDeliveryError {
+    constructor(code, details) {
+        super('RetryableReactionError', code, details);
+    }
+}
+/** A handler failure that should be dead-lettered immediately. */
+export class PermanentReactionError extends ReactionDeliveryError {
+    constructor(code, details) {
+        super('PermanentReactionError', code, details);
+    }
+}
+function requiredLifecycle(storage) {
+    if (storage.claimReactions === undefined ||
+        storage.completeReaction === undefined ||
+        storage.extendReactionLease === undefined ||
+        storage.failReaction === undefined) {
+        throw new Error('storage does not implement durable reaction delivery');
+    }
+}
+/** Host-driven worker. Call `runOnce` from the host scheduler or queue wake. */
+export class ReactionRunner {
+    #options;
+    #types;
+    #clock;
+    #leaseDurationMs;
+    #batchSize;
+    #initialBackoffMs;
+    #maxBackoffMs;
+    constructor(options) {
+        requiredLifecycle(options.storage);
+        assertName(options.workerId, 'workerId', 128);
+        this.#types = Object.keys(options.handlers).sort();
+        if (this.#types.length === 0 || this.#types.length > 64) {
+            throw new Error('reaction runner requires from 1 through 64 handlers');
+        }
+        for (const type of this.#types)
+            assertName(type, 'handler type', 128);
+        this.#leaseDurationMs =
+            options.leaseDurationMs ?? DEFAULT_REACTION_LEASE_MS;
+        this.#batchSize = options.batchSize ?? 10;
+        this.#initialBackoffMs =
+            options.initialBackoffMs ?? DEFAULT_REACTION_INITIAL_BACKOFF_MS;
+        this.#maxBackoffMs =
+            options.maxBackoffMs ?? DEFAULT_REACTION_MAX_BACKOFF_MS;
+        for (const [name, value] of [
+            ['leaseDurationMs', this.#leaseDurationMs],
+            ['batchSize', this.#batchSize],
+            ['initialBackoffMs', this.#initialBackoffMs],
+            ['maxBackoffMs', this.#maxBackoffMs],
+        ]) {
+            if (!Number.isSafeInteger(value) || value < 1) {
+                throw new Error(`${name} must be a positive safe integer`);
+            }
+        }
+        if (this.#batchSize > 100)
+            throw new Error('batchSize cannot exceed 100');
+        if (this.#initialBackoffMs > this.#maxBackoffMs) {
+            throw new Error('initialBackoffMs cannot exceed maxBackoffMs');
+        }
+        this.#options = options;
+        this.#clock = options.clock ?? Date.now;
+    }
+    async runOnce() {
+        const claim = this.#options.storage.claimReactions;
+        const complete = this.#options.storage.completeReaction;
+        const extend = this.#options.storage.extendReactionLease;
+        const fail = this.#options.storage.failReaction;
+        if (claim === undefined ||
+            complete === undefined ||
+            extend === undefined ||
+            fail === undefined) {
+            throw new Error('storage lost durable reaction delivery support');
+        }
+        const leaseOwner = `${this.#options.workerId}:${crypto.randomUUID()}`;
+        const reactions = await claim.call(this.#options.storage, this.#options.partition, {
+            leaseOwner,
+            types: this.#types,
+            nowMs: this.#clock(),
+            leaseDurationMs: this.#leaseDurationMs,
+            limit: this.#batchSize,
+        });
+        let completed = 0;
+        let retried = 0;
+        let deadLettered = 0;
+        let lostLeases = 0;
+        for (const reaction of reactions) {
+            const events = this.#options.events;
+            const startedAtMs = this.#clock();
+            const stillOwned = await extend.call(this.#options.storage, this.#options.partition, reaction.idempotencyKey, leaseOwner, Math.min(Number.MAX_SAFE_INTEGER, startedAtMs + this.#leaseDurationMs));
+            if (!stillOwned) {
+                lostLeases += 1;
+                continue;
+            }
+            if (events !== undefined) {
+                emitEvent(events, {
+                    type: 'reaction.started',
+                    atMs: startedAtMs,
+                    partition: this.#options.partition,
+                    workerId: this.#options.workerId,
+                    idempotencyKey: reaction.idempotencyKey,
+                    reactionType: reaction.type,
+                    version: reaction.version,
+                    attempt: reaction.attempts,
+                });
+            }
+            let handlerFailed = false;
+            let handlerError;
+            try {
+                const handler = this.#options.handlers[reaction.type];
+                if (handler === undefined) {
+                    throw new PermanentReactionError('reaction.handler_missing');
+                }
+                await handler({
+                    partition: this.#options.partition,
+                    idempotencyKey: reaction.idempotencyKey,
+                    type: reaction.type,
+                    version: reaction.version,
+                    payload: reaction.payload,
+                    attempt: reaction.attempts,
+                    maxAttempts: reaction.maxAttempts,
+                    sourceClientId: reaction.sourceClientId,
+                    sourceClientCommitId: reaction.sourceClientCommitId,
+                    sourceCommitSeq: reaction.sourceCommitSeq,
+                    extendLease: async () => {
+                        const renewed = await extend.call(this.#options.storage, this.#options.partition, reaction.idempotencyKey, leaseOwner, Math.min(Number.MAX_SAFE_INTEGER, this.#clock() + this.#leaseDurationMs));
+                        if (!renewed)
+                            throw new Error('reaction lease ownership lost');
+                    },
+                });
+            }
+            catch (error) {
+                handlerFailed = true;
+                handlerError = error;
+            }
+            if (!handlerFailed) {
+                const atMs = this.#clock();
+                const acknowledged = await complete.call(this.#options.storage, this.#options.partition, reaction.idempotencyKey, leaseOwner, atMs);
+                if (!acknowledged) {
+                    lostLeases += 1;
+                    continue;
+                }
+                completed += 1;
+                if (events !== undefined) {
+                    emitEvent(events, {
+                        type: 'reaction.completed',
+                        atMs,
+                        partition: this.#options.partition,
+                        workerId: this.#options.workerId,
+                        idempotencyKey: reaction.idempotencyKey,
+                        reactionType: reaction.type,
+                        version: reaction.version,
+                        attempt: reaction.attempts,
+                    });
+                }
+                continue;
+            }
+            const atMs = this.#clock();
+            const permanent = handlerError instanceof PermanentReactionError;
+            const failure = {
+                code: handlerError instanceof ReactionDeliveryError
+                    ? handlerError.code
+                    : 'reaction.handler_failed',
+                atMs,
+                ...(handlerError instanceof ReactionDeliveryError &&
+                    handlerError.details !== undefined
+                    ? { details: handlerError.details }
+                    : {}),
+            };
+            const deadLetter = permanent || reaction.attempts >= reaction.maxAttempts;
+            const retryAtMs = deadLetter
+                ? undefined
+                : Math.min(Number.MAX_SAFE_INTEGER, atMs +
+                    Math.min(this.#maxBackoffMs, this.#initialBackoffMs *
+                        2 ** Math.min(30, reaction.attempts - 1)));
+            const recorded = await fail.call(this.#options.storage, this.#options.partition, reaction.idempotencyKey, {
+                leaseOwner,
+                failure,
+                ...(retryAtMs !== undefined ? { retryAtMs } : {}),
+            });
+            if (!recorded) {
+                lostLeases += 1;
+                continue;
+            }
+            if (retryAtMs !== undefined) {
+                retried += 1;
+                if (events !== undefined) {
+                    emitEvent(events, {
+                        type: 'reaction.retried',
+                        atMs,
+                        partition: this.#options.partition,
+                        workerId: this.#options.workerId,
+                        idempotencyKey: reaction.idempotencyKey,
+                        reactionType: reaction.type,
+                        version: reaction.version,
+                        attempt: reaction.attempts,
+                        nextAttemptAtMs: retryAtMs,
+                        errorCode: failure.code,
+                    });
+                }
+            }
+            else {
+                deadLettered += 1;
+                if (events !== undefined) {
+                    emitEvent(events, {
+                        type: 'reaction.dead_lettered',
+                        atMs,
+                        partition: this.#options.partition,
+                        workerId: this.#options.workerId,
+                        idempotencyKey: reaction.idempotencyKey,
+                        reactionType: reaction.type,
+                        version: reaction.version,
+                        attempt: reaction.attempts,
+                        errorCode: failure.code,
+                    });
+                }
+            }
+        }
+        return {
+            claimed: reactions.length,
+            completed,
+            retried,
+            deadLettered,
+            lostLeases,
+        };
+    }
+}
+/** Explicit operator action for a dead-lettered reaction. */
+export async function retryDeadLetterReaction(options) {
+    if (options.storage.retryReaction === undefined) {
+        throw new Error('storage does not implement durable reaction retry');
+    }
+    return options.storage.retryReaction(options.partition, options.idempotencyKey, options.nowMs ?? Date.now());
+}
+/** Delete one bounded batch of aged completed and dead-lettered rows. */
+export async function pruneReactions(options) {
+    const retention = {
+        ...DEFAULT_REACTION_RETENTION,
+        ...options.retention,
+    };
+    if (!Number.isSafeInteger(options.nowMs)) {
+        throw new Error('nowMs must be a safe integer');
+    }
+    for (const [name, value] of [
+        ['completedRetentionMs', retention.completedRetentionMs],
+        ['deadLetterRetentionMs', retention.deadLetterRetentionMs],
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new Error(`${name} must be a non-negative safe integer`);
+        }
+    }
+    if (!Number.isSafeInteger(retention.batchSize) ||
+        retention.batchSize < 1 ||
+        retention.batchSize > 10_000) {
+        throw new Error('batchSize must be from 1 through 10000');
+    }
+    const prune = options.storage.pruneReactions;
+    if (prune === undefined) {
+        throw new Error('storage does not implement durable reaction pruning');
+    }
+    const completedBeforeMs = Math.max(Number.MIN_SAFE_INTEGER, options.nowMs - retention.completedRetentionMs);
+    const deadLetterBeforeMs = Math.max(Number.MIN_SAFE_INTEGER, options.nowMs - retention.deadLetterRetentionMs);
+    const removed = await prune.call(options.storage, options.partition, {
+        completedBeforeMs,
+        deadLetterBeforeMs,
+        limit: retention.batchSize,
+    });
+    const result = {
+        completedBeforeMs,
+        deadLetterBeforeMs,
+        removedCompleted: removed.completed,
+        removedDeadLetter: removed.deadLetter,
+        mayHaveMore: removed.completed + removed.deadLetter === retention.batchSize,
+    };
+    if (options.events !== undefined) {
+        emitEvent(options.events, {
+            type: 'reaction.prune_completed',
+            atMs: options.nowMs,
+            partition: options.partition,
+            limit: retention.batchSize,
+            ...result,
+        });
+    }
+    return result;
+}
+/** Helper used by the push path after commit sequence allocation. */
+export function toNewReactions(prepared, source) {
+    return prepared.map((reaction) => ({
+        ...reaction,
+        sourceClientId: source.clientId,
+        sourceClientCommitId: source.clientCommitId,
+        sourceCommitSeq: source.commitSeq,
+        createdAtMs: source.createdAtMs,
+    }));
+}

package/dist/realtime.js

@@ -14,7 +14,7 @@
  * the `sync` wake-up (§8.3).
  */
 import { DecodeError, decodeMessage, encodeMessage, encodePresenceError, encodePresenceFanout, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimePresencePublish, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
-import { RESOLVER_OUTAGE } from './context.js';
+import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE } from './context.js';
 import { SyncError, syncError } from './errors.js';
 import { emitEvent } from './events.js';
 import { createSyncResponseStream } from './handler.js';
@@ -770,6 +770,9 @@ export class RealtimeHub {
     async connect(options) {
         const { storage } = this.#config;
         const clock = this.#config.clock ?? Date.now;
+        if (options.clientId.startsWith(REMOTE_COMMAND_CLIENT_ID_PREFIX)) {
+            throw syncError('sync.invalid_client_id', 'clientId uses a reserved server-command namespace (§1.5)');
+        }
         const record = await storage.getClientRecord(options.partition, options.clientId);
         if (record !== undefined && record.actorId !== options.actorId) {
             throw syncError('sync.invalid_client_id', 'clientId is bound to a different actor in this partition (§1.5)');

package/dist/sqlite-dialect.d.ts

@@ -30,7 +30,7 @@ import type { StoredChange, StoredCommit, StoredPushResult, StoredRow } from './
  * the Postgres storage documents (§3.1, performance-by-
  * construction).
  */
-export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq INTEGER NOT NULL DEFAULT 0,\n  horizon_seq INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n  row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result TEXT NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n  updated_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\n";
+export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq INTEGER NOT NULL DEFAULT 0,\n  horizon_seq INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n  row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result TEXT NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n  last_failure TEXT,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n  updated_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\n";
 /** Split the DDL into individual statements (D1 applies them one by one). */
 export declare function sqliteDdlStatements(): string[];
 /** `?,?,…` for an `IN (…)` clause of `count` positional parameters. */

package/dist/sqlite-dialect.js

@@ -49,6 +49,26 @@ CREATE TABLE IF NOT EXISTS sync_push_results(
   client_commit_id TEXT NOT NULL, result TEXT NOT NULL,
   PRIMARY KEY(partition, client_id, client_commit_id)
 );
+CREATE TABLE IF NOT EXISTS sync_reactions(
+  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,
+  type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,
+  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,
+  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,
+  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,
+  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,
+  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,
+  last_failure TEXT,
+  PRIMARY KEY(partition, idempotency_key),
+  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))
+);
+CREATE INDEX IF NOT EXISTS sync_reactions_due
+  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);
+CREATE INDEX IF NOT EXISTS sync_reactions_lease
+  ON sync_reactions(partition, status, lease_expires_at_ms);
+CREATE INDEX IF NOT EXISTS sync_reactions_completed
+  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);
+CREATE INDEX IF NOT EXISTS sync_reactions_dead_letter
+  ON sync_reactions(partition, status, available_at_ms, idempotency_key);
 CREATE TABLE IF NOT EXISTS sync_clients(
   partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,
   cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,

package/dist/sqlite-storage.d.ts

@@ -8,7 +8,7 @@
  */
 import { Database } from 'bun:sqlite';
 import type { CompiledSchema, CompiledTable } from './schema.js';
-import type { ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export declare class SqliteServerStorage implements ServerStorage {
     #private;
     readonly db: Database;
@@ -20,12 +20,21 @@ export declare class SqliteServerStorage implements ServerStorage {
     /** Internal: write a row + refresh its scope-index entries. */
     writeRow(partition: string, table: string, row: StoredRow): void;
     getMaxCommitSeq(partition: string): Promise<number>;
+    queryAuthoritative(partition: string, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
     getHorizonSeq(partition: string): Promise<number>;
     setHorizonSeq(partition: string, seq: number): Promise<void>;
     pruneCommitsThrough(partition: string, seq: number): Promise<number>;
     getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
     getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
     getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
+    claimReactions(partition: string, query: ReactionClaimQuery): Promise<StoredReaction[]>;
+    completeReaction(partition: string, idempotencyKey: string, leaseOwner: string, completedAtMs: number): Promise<boolean>;
+    extendReactionLease(partition: string, idempotencyKey: string, leaseOwner: string, leaseExpiresAtMs: number): Promise<boolean>;
+    failReaction(partition: string, idempotencyKey: string, update: ReactionFailureUpdate): Promise<boolean>;
+    retryReaction(partition: string, idempotencyKey: string, nowMs: number): Promise<boolean>;
+    getReaction(partition: string, idempotencyKey: string): Promise<StoredReaction | undefined>;
+    listReactions(partition: string, query: ReactionListQuery): Promise<StoredReaction[]>;
+    pruneReactions(partition: string, query: ReactionPruneQuery): Promise<PrunedReactionCounts>;
     readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
     scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;