@syncular/server 0.15.44 → 0.15.46

package/dist/pg-executor.d.ts

@@ -1,5 +1,5 @@
 /**
- * The minimal Postgres executor seam (REVISE B2: zero runtime deps).
+ * The minimal Postgres executor seam has zero runtime dependencies.
  *
  * `PostgresServerStorage` is written entirely against this interface so the
  * server library never imports a specific driver. Production wires one of:

package/dist/pg-executor.js

@@ -1,5 +1,5 @@
 /**
- * The minimal Postgres executor seam (REVISE B2: zero runtime deps).
+ * The minimal Postgres executor seam has zero runtime dependencies.
  *
  * `PostgresServerStorage` is written entirely against this interface so the
  * server library never imports a specific driver. Production wires one of:

package/dist/postgres-fanout.d.ts

@@ -1,5 +1,5 @@
 /**
- * LISTEN/NOTIFY multi-instance fanout (TODO §4.1) — the primitive that lets
+ * LISTEN/NOTIFY multi-instance fanout lets
  * N server instances behind a load balancer wake each other's realtime
  * sessions when a commit lands on any one of them.
  *

package/dist/postgres-storage.d.ts

@@ -1,6 +1,6 @@
 import { type PgExecutor } from './pg-executor.js';
 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';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -23,7 +23,7 @@ import type { ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuer
  *     set, §5.9.5) as an index range, never a scan. `postgres-explain
  *     .test.ts` asserts an `Index` node here too.
  */
-export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT 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 BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT 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 BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\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 BIGINT 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 JSONB 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 BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT 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 POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT 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 BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT 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 BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\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 BIGINT 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 JSONB 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 JSONB NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,\n  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,\n  last_failure JSONB,\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 BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT 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 class PostgresServerStorage implements ServerStorage {
     #private;
     constructor(exec: PgExecutor);
@@ -42,12 +42,21 @@ export declare class PostgresServerStorage implements ServerStorage {
      */
     begin(partition: string): Promise<StorageTransaction>;
     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[]>;

package/dist/postgres-storage.js

@@ -1,3 +1,4 @@
+import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
 import { commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
@@ -63,6 +64,26 @@ CREATE TABLE IF NOT EXISTS sync_push_results(
   client_commit_id TEXT NOT NULL, result JSONB 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 JSONB NOT NULL,
+  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,
+  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,
+  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,
+  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,
+  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,
+  last_failure JSONB,
+  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 BIGINT NOT NULL, subscriptions JSONB NOT NULL,
@@ -83,6 +104,32 @@ function toBase64(bytes) {
 function fromBase64(text) {
     return new Uint8Array(Buffer.from(text, 'base64'));
 }
+function toStoredReaction(record) {
+    return {
+        idempotencyKey: record.idempotency_key,
+        type: record.type,
+        version: asNumber(record.version),
+        payload: asJson(record.payload),
+        sourceClientId: record.source_client_id,
+        sourceClientCommitId: record.source_client_commit_id,
+        sourceCommitSeq: asNumber(record.source_commit_seq),
+        createdAtMs: asNumber(record.created_at_ms),
+        maxAttempts: asNumber(record.max_attempts),
+        status: record.status,
+        attempts: asNumber(record.attempts),
+        availableAtMs: asNumber(record.available_at_ms),
+        ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
+        ...(record.lease_expires_at_ms !== null
+            ? { leaseExpiresAtMs: asNumber(record.lease_expires_at_ms) }
+            : {}),
+        ...(record.completed_at_ms !== null
+            ? { completedAtMs: asNumber(record.completed_at_ms) }
+            : {}),
+        ...(record.last_failure !== null
+            ? { lastFailure: asJson(record.last_failure) }
+            : {}),
+    };
+}
 /**
  * Serialize a push result to a JSON-able object (stored in a JSONB column).
  * `serverRow` bytes are base64-encoded — JSONB cannot hold raw bytes.
@@ -191,8 +238,8 @@ function toStoredChange(record) {
     };
 }
 /**
- * Migration rewrite (DESIGN "optional materialization"): keyset-paged walk
- * of a row table inside the migration transaction; when `oldLayout` is
+ * Migration rewrite: keyset-paged walk of a row table inside the migration
+ * transaction. When `oldLayout` is
  * given every payload re-encodes under the current columns, and the
  * projection (when materialized) refreshes from the payload either way.
  */
@@ -425,6 +472,27 @@ class PostgresTransaction {
             JSON.stringify(serializePushResult(result)),
         ]);
     }
+    async enqueueReactions(reactions) {
+        this.#assertOpen();
+        for (const reaction of reactions) {
+            await this.#client.query(`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 ($1,$2,$3,$4,$5,$6,$7,$8,$9,$9,'pending',0,$10)`, [
+                this.#partition,
+                reaction.idempotencyKey,
+                reaction.type,
+                reaction.version,
+                JSON.stringify(reaction.payload),
+                reaction.sourceClientId,
+                reaction.sourceClientCommitId,
+                reaction.sourceCommitSeq,
+                reaction.createdAtMs,
+                reaction.maxAttempts,
+            ]);
+        }
+    }
     async commit() {
         this.#assertOpen();
         this.#open = false;
@@ -599,6 +667,23 @@ export class PostgresServerStorage {
         const { rows } = await this.#exec.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [partition]);
         return rows[0] === undefined ? 0 : asNumber(rows[0].max_commit_seq);
     }
+    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);
+        return this.#exec.transaction(async (client) => {
+            await client.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
+            const result = await client.query(postgresPlaceholders(prepared.sql), prepared.params);
+            const cursor = await client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [partition]);
+            return {
+                rows: result.rows,
+                maxCommitSeq: cursor.rows[0] === undefined
+                    ? 0
+                    : asNumber(cursor.rows[0].max_commit_seq),
+            };
+        });
+    }
     async getHorizonSeq(partition) {
         const { rows } = await this.#exec.query('SELECT horizon_seq FROM sync_partitions WHERE partition=$1', [partition]);
         return rows[0] === undefined ? 0 : asNumber(rows[0].horizon_seq);
@@ -624,6 +709,141 @@ export class PostgresServerStorage {
     getPushResult(partition, clientId, clientCommitId) {
         return getPushResultOn(this.#exec, partition, clientId, clientCommitId);
     }
+    async claimReactions(partition, query) {
+        if (query.types.length === 0 || query.limit <= 0)
+            return [];
+        const typeParams = query.types.map((_, index) => `$${index + 2}`).join(',');
+        const nowParam = query.types.length + 2;
+        const limitParam = nowParam + 1;
+        const workerParam = limitParam + 1;
+        const expiresParam = workerParam + 1;
+        const { rows } = await this.#exec.query(`WITH due AS (
+         SELECT partition, idempotency_key
+           FROM sync_reactions
+          WHERE partition=$1 AND type IN (${typeParams})
+            AND ((status='pending' AND available_at_ms<=$${nowParam})
+              OR (status='leased' AND lease_expires_at_ms<=$${nowParam}))
+          ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
+                        ELSE available_at_ms END,
+                   created_at_ms, idempotency_key
+          FOR UPDATE SKIP LOCKED
+          LIMIT $${limitParam}
+       )
+       UPDATE sync_reactions AS reaction
+          SET status='leased', attempts=reaction.attempts+1,
+              lease_owner=$${workerParam}, lease_expires_at_ms=$${expiresParam},
+              completed_at_ms=NULL
+         FROM due
+        WHERE reaction.partition=due.partition
+          AND reaction.idempotency_key=due.idempotency_key
+      RETURNING reaction.*`, [
+            partition,
+            ...query.types,
+            query.nowMs,
+            query.limit,
+            query.leaseOwner,
+            Math.min(Number.MAX_SAFE_INTEGER, query.nowMs + query.leaseDurationMs),
+        ]);
+        return rows
+            .map(toStoredReaction)
+            .sort((a, b) => a.createdAtMs - b.createdAtMs ||
+            a.idempotencyKey.localeCompare(b.idempotencyKey));
+    }
+    async completeReaction(partition, idempotencyKey, leaseOwner, completedAtMs) {
+        const result = await this.#exec.query(`UPDATE sync_reactions
+          SET status='completed', completed_at_ms=$4,
+              lease_owner=NULL, lease_expires_at_ms=NULL
+        WHERE partition=$1 AND idempotency_key=$2
+          AND status='leased' AND lease_owner=$3`, [partition, idempotencyKey, leaseOwner, completedAtMs]);
+        return result.rowCount === 1;
+    }
+    async extendReactionLease(partition, idempotencyKey, leaseOwner, leaseExpiresAtMs) {
+        const result = await this.#exec.query(`UPDATE sync_reactions SET lease_expires_at_ms=$4
+        WHERE partition=$1 AND idempotency_key=$2
+          AND status='leased' AND lease_owner=$3`, [partition, idempotencyKey, leaseOwner, leaseExpiresAtMs]);
+        return result.rowCount === 1;
+    }
+    async failReaction(partition, idempotencyKey, update) {
+        const result = await this.#exec.query(`UPDATE sync_reactions
+          SET status=$4, available_at_ms=$5, last_failure=$6,
+              lease_owner=NULL, lease_expires_at_ms=NULL
+        WHERE partition=$1 AND idempotency_key=$2
+          AND status='leased' AND lease_owner=$3`, [
+            partition,
+            idempotencyKey,
+            update.leaseOwner,
+            update.retryAtMs === undefined ? 'dead-letter' : 'pending',
+            update.retryAtMs ?? update.failure.atMs,
+            JSON.stringify(update.failure),
+        ]);
+        return result.rowCount === 1;
+    }
+    async retryReaction(partition, idempotencyKey, nowMs) {
+        const result = await this.#exec.query(`UPDATE sync_reactions
+          SET status='pending', attempts=0, available_at_ms=$3,
+              last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
+              completed_at_ms=NULL
+        WHERE partition=$1 AND idempotency_key=$2 AND status='dead-letter'`, [partition, idempotencyKey, nowMs]);
+        return result.rowCount === 1;
+    }
+    async getReaction(partition, idempotencyKey) {
+        const { rows } = await this.#exec.query('SELECT * FROM sync_reactions WHERE partition=$1 AND idempotency_key=$2', [partition, idempotencyKey]);
+        return rows[0] === undefined ? undefined : toStoredReaction(rows[0]);
+    }
+    async listReactions(partition, query) {
+        const where = ['partition=$1'];
+        const params = [partition];
+        if (query.statuses !== undefined && query.statuses.length > 0) {
+            const placeholders = query.statuses.map((_, index) => `$${params.length + index + 1}`);
+            where.push(`status IN (${placeholders.join(',')})`);
+            params.push(...query.statuses);
+        }
+        if (query.types !== undefined && query.types.length > 0) {
+            const placeholders = query.types.map((_, index) => `$${params.length + index + 1}`);
+            where.push(`type IN (${placeholders.join(',')})`);
+            params.push(...query.types);
+        }
+        params.push(query.limit);
+        const { rows } = await this.#exec.query(`SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
+        ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT $${params.length}`, params);
+        return rows.map(toStoredReaction);
+    }
+    async pruneReactions(partition, query) {
+        if (query.limit <= 0)
+            return { completed: 0, deadLetter: 0 };
+        const { rows } = await this.#exec.query(`WITH targets AS (
+         SELECT partition, idempotency_key
+           FROM sync_reactions
+          WHERE partition=$1
+            AND ((status='completed' AND completed_at_ms IS NOT NULL
+                  AND completed_at_ms<$2)
+              OR (status='dead-letter' AND available_at_ms<$3))
+          ORDER BY CASE WHEN status='completed' THEN completed_at_ms
+                        ELSE available_at_ms END,
+                   idempotency_key
+          FOR UPDATE SKIP LOCKED
+          LIMIT $4
+       )
+       DELETE FROM sync_reactions AS reaction
+        USING targets
+        WHERE reaction.partition=targets.partition
+          AND reaction.idempotency_key=targets.idempotency_key
+          AND ((reaction.status='completed'
+                AND reaction.completed_at_ms IS NOT NULL
+                AND reaction.completed_at_ms<$2)
+            OR (reaction.status='dead-letter'
+                AND reaction.available_at_ms<$3))
+      RETURNING reaction.status`, [
+            partition,
+            query.completedBeforeMs,
+            query.deadLetterBeforeMs,
+            query.limit,
+        ]);
+        return {
+            completed: rows.filter((row) => row.status === 'completed').length,
+            deadLetter: rows.filter((row) => row.status === 'dead-letter').length,
+        };
+    }
     async readCommitWindow(partition, query) {
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];
@@ -818,7 +1038,7 @@ export class PostgresServerStorage {
         const { rows } = await this.#exec.query('SELECT DISTINCT blob_id FROM sync_blob_refs WHERE partition=$1', [partition]);
         return rows.map((r) => r.blob_id);
     }
-    // -- admin/console read surface (TODO §2.5) --------------------------------
+    // -- admin/console read surface --------------------------------------------
     async listClientRecords(partition) {
         const { rows } = await this.#exec.query('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 ORDER BY updated_at_ms DESC', [partition]);
         return rows.map((r) => ({

package/dist/pull.js

@@ -170,7 +170,7 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
     // builder through `sqliteImageBuilder`; when omitted we default to the
     // in-tree `buildSqliteImage` ONLY on a Bun runtime, reached by a *dynamic*
     // import so `bun:sqlite` is never a static dependency of the pull path
-    // (TODO §4.2 neutrality — enforced by test/runtime-neutrality.test.ts). On
+    // (runtime neutrality is enforced by test/runtime-neutrality.test.ts). On
     // Workers/edge (no `Bun`) this yields the rows lane for a bit-2 client — a
     // support floor, not a fallback (§5.3: sqlite is an *accept*, not a demand).
     const buildImage = await resolveImageBuilder(ctx);

package/dist/push.d.ts

@@ -17,11 +17,11 @@
  * merge); a validator throw rejects the whole commit atomically with a
  * host code.
  */
-import { type PushCommitFrame, type PushResultFrame } from '@syncular/core';
+import { type PushCommitFrame, type PushOperation, type PushResultFrame } from '@syncular/core';
 import type { SyncRequestContext } from './context.js';
 import type { CompiledSchema } from './schema.js';
 import type { ResolvedScopes } from './scopes.js';
-import type { StoredCommit } from './storage.js';
+import type { StorageTransaction, StoredCommit } from './storage.js';
 export interface ProcessedPushCommit {
     readonly frame: PushResultFrame;
     /** True when this request observed an already-recorded idempotency outcome. */
@@ -43,3 +43,9 @@ export declare function processPushCommit(ctx: SyncRequestContext, schema: Compi
  * cache provenance needed by structured events and server helpers.
  */
 export declare function processPushCommitWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame): Promise<ProcessedPushCommit>;
+/**
+ * Shared serialized apply path for SSP2 commits and authoritative commands.
+ * The builder runs after the partition lock and idempotency re-check, so its
+ * reads and the returned operations share the transaction that is committed.
+ */
+export declare function processPushOperationsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, clientCommitId: string, buildOperations: (tx: StorageTransaction) => Promise<readonly PushOperation[]>): Promise<ProcessedPushCommit>;

package/dist/push.js

@@ -20,6 +20,8 @@
 import { decodeRow, encodeRow, parseBlobRef, } from '@syncular/core';
 import { clockOf } from './context.js';
 import { SyncError } from './errors.js';
+import { emitEvent } from './events.js';
+import { prepareReactions, toNewReactions, } from './reactions.js';
 import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes.js';
 import { StorageConstraintError } from './storage-errors.js';
 import { CommitValidationRejection, toValidateRow, ValidationRejection, } from './validate.js';
@@ -514,10 +516,18 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
  * cache provenance needed by structured events and server helpers.
  */
 export async function processPushCommitWithTrace(ctx, schema, resolved, clientId, frame) {
+    return processPushOperationsWithTrace(ctx, schema, resolved, clientId, frame.clientCommitId, async () => frame.operations);
+}
+/**
+ * Shared serialized apply path for SSP2 commits and authoritative commands.
+ * The builder runs after the partition lock and idempotency re-check, so its
+ * reads and the returned operations share the transaction that is committed.
+ */
+export async function processPushOperationsWithTrace(ctx, schema, resolved, clientId, clientCommitId, buildOperations) {
     const { storage, partition } = ctx;
     let persisted;
     try {
-        persisted = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+        persisted = await storage.getPushResult(partition, clientId, clientCommitId);
     }
     catch (error) {
         if (error instanceof SyncError &&
@@ -525,28 +535,30 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
             // §6.3: answer the retryable cache-miss for this commit rather than
             // re-applying. Not persisted — a retry may find a readable record.
             return {
-                frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+                frame: idempotencyCacheMissFrame(clientCommitId, error),
                 replayed: false,
             };
         }
         throw error;
     }
     if (persisted !== undefined) {
-        return processedPushCommit(frame.clientCommitId, persisted, true);
+        return processedPushCommit(clientCommitId, persisted, true);
     }
     const createdAtMs = clockOf(ctx)();
     const blobCtx = { store: ctx.blobs, partition };
     const crdtMergers = ctx.crdtMergers;
     const validators = ctx.validators;
     const commitValidator = ctx.commitValidator;
+    const reactionPlanner = ctx.reactionPlanner;
     const tx = await storage.begin(partition);
     const lockPartitionForPush = tx.lockPartitionForPush?.bind(tx) ??
         tx.lockPartitionForCommitValidation?.bind(tx);
     const commitRejectedPushResult = tx.commitRejectedPushResult?.bind(tx);
     try {
         if (lockPartitionForPush === undefined ||
-            commitRejectedPushResult === undefined) {
-            throw new Error('storage transaction does not support serialized push apply and atomic rejection finalization');
+            commitRejectedPushResult === undefined ||
+            (reactionPlanner !== undefined && tx.enqueueReactions === undefined)) {
+            throw new Error('storage transaction does not support serialized push apply, atomic rejection finalization, and configured durable reactions');
         }
         await lockPartitionForPush();
         // The optimistic lookup above may have raced another delivery. Re-check
@@ -559,11 +571,11 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
         // transaction-scoped read observes it.
         try {
             const serializedPersisted = tx.getPushResult !== undefined
-                ? await tx.getPushResult(clientId, frame.clientCommitId)
-                : await storage.getPushResult(partition, clientId, frame.clientCommitId);
+                ? await tx.getPushResult(clientId, clientCommitId)
+                : await storage.getPushResult(partition, clientId, clientCommitId);
             if (serializedPersisted !== undefined) {
                 await tx.rollback();
-                return processedPushCommit(frame.clientCommitId, serializedPersisted, true);
+                return processedPushCommit(clientCommitId, serializedPersisted, true);
             }
         }
         catch (error) {
@@ -571,7 +583,7 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
                 error.code === 'sync.idempotency_cache_miss') {
                 await tx.rollback();
                 return {
-                    frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+                    frame: idempotencyCacheMissFrame(clientCommitId, error),
                     replayed: false,
                 };
             }
@@ -581,8 +593,9 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
         const changes = [];
         const validatedOperations = [];
         let terminated;
-        for (let opIndex = 0; opIndex < frame.operations.length; opIndex++) {
-            const op = frame.operations[opIndex];
+        const operations = await buildOperations(tx);
+        for (let opIndex = 0; opIndex < operations.length; opIndex++) {
+            const op = operations[opIndex];
             if (op === undefined)
                 continue;
             const outcome = await applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMergers, validators, partition, ctx.actorId);
@@ -596,11 +609,22 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
                 changes.push(outcome.change);
         }
         if (terminated === undefined) {
-            const commitReject = await runCommitValidator(commitValidator, tx, schema, clientId, frame.clientCommitId, ctx.actorId, partition, validatedOperations);
+            const commitReject = await runCommitValidator(commitValidator, tx, schema, clientId, clientCommitId, ctx.actorId, partition, validatedOperations);
             if (commitReject?.kind === 'terminate') {
                 terminated = commitReject.record;
             }
         }
+        let preparedReactions = [];
+        if (terminated === undefined && reactionPlanner !== undefined) {
+            preparedReactions = await prepareReactions(reactionPlanner, {
+                clientId,
+                clientCommitId,
+                actorId: ctx.actorId,
+                partition,
+                operations: validatedOperations,
+                read: commitValidationReader(tx, schema),
+            });
+        }
         if (terminated !== undefined) {
             // §6.3 rejected: only the terminating operation's record; §6.4:
             // every write of the commit rolls back.
@@ -610,27 +634,57 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
             });
             // Discard candidates and persist the rejection while retaining the same
             // partition lock. There is no unlock gap in which a duplicate can rerun.
-            await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
-            const canonical = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+            await commitRejectedPushResult(clientId, clientCommitId, stored);
+            const canonical = await storage.getPushResult(partition, clientId, clientCommitId);
             if (canonical === undefined) {
                 throw new Error('push rejection finalization did not persist an outcome');
             }
-            return processedPushCommit(frame.clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
+            return processedPushCommit(clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
         }
         const commitSeq = await tx.appendCommit({
             clientId,
-            clientCommitId: frame.clientCommitId,
+            clientCommitId,
             actorId: ctx.actorId,
             createdAtMs,
             changes,
         });
+        const newReactions = toNewReactions(preparedReactions, {
+            clientId,
+            clientCommitId,
+            commitSeq,
+            createdAtMs,
+        });
+        if (newReactions.length > 0) {
+            const enqueueReactions = tx.enqueueReactions;
+            if (enqueueReactions === undefined) {
+                throw new Error('storage lost durable reaction enqueue support');
+            }
+            await enqueueReactions.call(tx, newReactions);
+        }
         const stored = newStoredPushResult(createdAtMs, {
             status: 'applied',
             commitSeq,
             results,
         });
-        await tx.putPushResult(clientId, frame.clientCommitId, stored);
+        await tx.putPushResult(clientId, clientCommitId, stored);
         await tx.commit();
+        if (ctx.events !== undefined) {
+            const atMs = clockOf(ctx)();
+            for (const reaction of newReactions) {
+                emitEvent(ctx.events, {
+                    type: 'reaction.queued',
+                    atMs,
+                    partition,
+                    actorId: ctx.actorId,
+                    clientId,
+                    clientCommitId,
+                    commitSeq,
+                    idempotencyKey: reaction.idempotencyKey,
+                    reactionType: reaction.type,
+                    version: reaction.version,
+                });
+            }
+        }
         if (ctx.realtime !== undefined && changes.length > 0) {
             await ctx.realtime.notifyCommit(partition, {
                 commitSeq,
@@ -639,7 +693,7 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
                 changes,
             });
         }
-        return processedPushCommit(frame.clientCommitId, stored, false);
+        return processedPushCommit(clientCommitId, stored, false);
     }
     catch (error) {
         if (error instanceof StorageConstraintError) {
@@ -660,12 +714,12 @@ export async function processPushCommitWithTrace(ctx, schema, resolved, clientId
                 throw new Error('storage transaction lost atomic push rejection finalization support');
             }
             try {
-                await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
-                const canonical = await storage.getPushResult(partition, clientId, frame.clientCommitId);
+                await commitRejectedPushResult(clientId, clientCommitId, stored);
+                const canonical = await storage.getPushResult(partition, clientId, clientCommitId);
                 if (canonical === undefined) {
                     throw new Error('push rejection finalization did not persist an outcome');
                 }
-                return processedPushCommit(frame.clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
+                return processedPushCommit(clientCommitId, canonical, canonical.cacheIdentity !== stored.cacheIdentity);
             }
             catch (finalizationError) {
                 // A failed finalization must still release the transaction: on