@syncular/server 0.15.45 → 0.15.47

package/README.md

@@ -8,6 +8,17 @@ pruning (§4.6), and signed-URL token issuance (§5.4). `SPEC.md` is
 normative for everything on the wire; this README covers the **host
 surface** — in particular the ops seam and the pruning runbook.
 
+Application processes can expose generated named queries and transactional
+commands through `RemoteOperationRegistry`. Queries stay in the server
+registry, command mutations use the ordinary serialized push path, and
+`RemoteOperationWatchHub` provides live replacement snapshots. The protocol is
+specified in [`docs/REMOTE.md`](../../docs/REMOTE.md) and the practical setup is
+in the [remote operations guide](https://syncular.dev/guide-remote-operations/).
+
+Application intent belongs in immutable domain event rows written in the same
+commit as the state change. `SyncularServerEvents` below remains operational
+telemetry. See the [domain event guide](https://syncular.dev/guide-domain-events/).
+
 ## Deployment matrix (runtime adapters)
 
 The server core is **runtime-neutral TypeScript** — `handleSyncRequest` and
@@ -18,7 +29,7 @@ The supported set, and what deliberately does **not** get an adapter:
 
 | Runtime | Adapter | Transport | Storage | Status |
 | --- | --- | --- | --- | --- |
-| **Bun / Node** | `@syncular/server-hono` | HTTP (`POST /sync`, segments, blobs) **+ WS realtime** (§8, host-driven upgrade) | any: `SqliteServerStorage`, `PostgresServerStorage`, memory | **Supported now** — the reference deployment; runs the full conformance catalog on both bindings. |
+| **Bun / Node 22.13+** | `@syncular/server-hono` | HTTP (`POST /sync`, segments, blobs) **+ WS realtime** (§8, host-driven upgrade) | `SqliteServerStorage` through `@syncular/server/sqlite`, Postgres, memory | **Supported now** — the reference deployment; runs the full conformance catalog on both bindings. |
 | **Cloudflare Workers** | `@syncular/server-workers` | HTTP binding via Hono (Workers-native) **+ optional WS realtime** (§8) | `D1ServerStorage` behind one per-partition Durable Object queue; R2-as-S3 for segments/blobs | **Supported now** — D1 sync writes always traverse the DO; WebSocket upgrades remain optional. |
 | Raw Deno / edge-misc | — | — | — | **Not adapted** (policy below). |
 
@@ -65,9 +76,9 @@ or the storage projection cannot migrate:
 ```ts
 import {
   ensureSyncServerReady,
-  SqliteServerStorage,
   type SyncServerConfig,
 } from '@syncular/server';
+import { SqliteServerStorage } from '@syncular/server/sqlite';
 
 const config: SyncServerConfig = {
   schema,
@@ -80,6 +91,12 @@ await ensureSyncServerReady(config);
 Bun.serve({ fetch: app.fetch });
 ```
 
+`@syncular/server/sqlite` selects `bun:sqlite` on Bun and the built-in
+`node:sqlite` module on Node. It covers server storage, segment storage, blob
+storage, leases, and SQLite-image generation without an external SQLite
+package. The runtime-specific database wrappers are `BunSqliteDatabase` and
+`NodeSqliteDatabase` when a host needs direct access to the native handle.
+
 The helper accepts the generated `ServerSchema`, compiles it, and calls the
 storage backend's low-level `ensureSchema(CompiledSchema)`. A failure is a
 `SyncServerReadinessError` with stable code `sync.schema_not_ready`, a `phase`
@@ -263,6 +280,118 @@ must check for it and fail closed. See the public
 for a user-scoped key-grant table revoked through a Workspace index and for the
 atomic reverse-index/queue fallback required by ordered or derived lookups.
 
+## Durable server reactions
+
+`reactionPlanner` turns an accepted candidate commit into bounded work records.
+It runs after operation and whole-commit validation, inside the authoritative
+push transaction. It may use the candidate-state reader and must perform no
+external side effects. A rejected or replayed commit does not run it.
+
+```ts
+import {
+  ReactionRunner,
+  type ReactionPlanner,
+  type SyncServerConfig,
+} from '@syncular/server';
+
+type AppReactions = {
+  'invoice.email': { invoiceId: string };
+};
+
+const reactionPlanner: ReactionPlanner<AppReactions> = ({ operations }) =>
+  operations.flatMap((operation) =>
+    operation.table === 'invoice_events' &&
+    operation.row?.kind === 'invoice_finalized' &&
+    typeof operation.row.invoice_id === 'string'
+      ? [{
+          key: `invoice:${operation.row.invoice_id}`,
+          type: 'invoice.email',
+          version: 1,
+          payload: { invoiceId: operation.row.invoice_id },
+          maxAttempts: 8,
+        }]
+      : [],
+  );
+
+const config: SyncServerConfig = {
+  schema, storage, segments, resolveScopes, reactionPlanner,
+};
+```
+
+App rows, commit metadata, reaction rows, and the push idempotency result land
+in one transaction. The handler idempotency key is derived from the source
+`partition`, `clientId`, `clientCommitId`, and planner `key`. Reaction rows use
+their own partition-scoped table and survive `pruneCommitLog`.
+
+Drive delivery from a host scheduler or queue wake:
+
+```ts
+const runner = new ReactionRunner<AppReactions>({
+  storage,
+  partition: 'main',
+  workerId: 'invoice-worker-1',
+  handlers: {
+    'invoice.email': async ({ payload, idempotencyKey, extendLease }) => {
+      await extendLease();
+      await emailProvider.send({
+        invoiceId: payload.invoiceId,
+        idempotencyKey,
+      });
+    },
+  },
+});
+
+await runner.runOnce();
+```
+
+Claims and acknowledgements compare a lease owner. Expired leases can be
+claimed by another worker, and long handlers can call `extendLease()`. Ordinary
+throws and `RetryableReactionError` retry with bounded exponential backoff.
+`PermanentReactionError` and exhausted retry limits enter `dead-letter`.
+`retryDeadLetterReaction` resets one row for an explicit operator retry.
+Each `runOnce()` uses a fresh lease token and rechecks ownership before
+starting every handler in a claimed batch.
+
+Schedule terminal retention separately from commit-log pruning:
+
+```ts
+import { pruneReactions } from '@syncular/server';
+
+let result;
+do {
+  result = await pruneReactions({
+    storage,
+    partition: 'main',
+    nowMs: Date.now(),
+    events,
+  });
+} while (result.mayHaveMore);
+```
+
+Defaults retain completed rows for 30 days, dead-lettered rows for 90 days,
+and remove at most 1,000 rows per pass. Override them with
+`retention: { completedRetentionMs, deadLetterRetentionMs, batchSize }`.
+Only terminal rows strictly older than their cutoff are eligible. Pending and
+leased work is preserved, including expired leases. Cleanup and manual retry
+serialize at storage, so one transition wins a race. Each pass emits
+`reaction.prune_completed` with both cutoffs, both removal counts, the limit,
+and `mayHaveMore`.
+
+Delivery is at least once. A crash after the handler's external call and before
+acknowledgement can run that call again. Handlers receive the same stable
+`idempotencyKey` on every attempt and should pass it to external providers.
+Syncular does not claim exactly-once external effects.
+
+Planned payloads are plain JSON, versioned, limited to 64 KiB and 16 levels,
+with at most 100 reactions per commit. Failure details are plain JSON limited
+to 8 KiB. The planner API cannot enforce purity in JavaScript; running an
+external effect from the planner violates the transaction contract.
+
+SQLite and PostgreSQL use their existing push transactions. D1 appends the
+reaction writes to the same atomic batch as the source commit and retains its
+mandatory per-partition Durable Object coordination for pushes. D1 claims use
+one `UPDATE ... RETURNING` statement, so there is no claim read/write gap.
+
 ## Structured events (the ops seam)
 
 One optional interface, `SyncularServerEvents`, carries every
@@ -310,6 +439,12 @@ context). The demo server wires it behind `SYNCULAR_DEMO_EVENTS=1`.
 | `push.applied` | A `PUSH_COMMIT` applied, or replayed from the idempotency cache (§2.3) | `clientId`, `clientCommitId`, `operations`, `commitSeq?`, `replay` |
 | `push.rejected` | A commit rejected (§6.3) | `clientId`, `clientCommitId`, `operations`, `code` (§10.2), `opIndex` |
 | `push.conflicted` | A commit terminated by a version conflict (§6.2) | `clientId`, `clientCommitId`, `operations`, `opIndex` |
+| `reaction.queued` | A planned reaction committed with its source push | `clientId`, `clientCommitId`, `commitSeq`, `idempotencyKey`, `reactionType`, `version` |
+| `reaction.started` | A worker claimed and began one attempt | `workerId`, `idempotencyKey`, `reactionType`, `version`, `attempt` |
+| `reaction.retried` | A retryable attempt failed and was rescheduled | started fields plus `nextAttemptAtMs`, `errorCode` |
+| `reaction.completed` | A handler finished and its owner acknowledged | started fields |
+| `reaction.dead_lettered` | A permanent or exhausted failure was recorded | started fields plus `errorCode` |
+| `reaction.prune_completed` | One bounded terminal-reaction retention pass finished | `completedBeforeMs`, `deadLetterBeforeMs`, `limit`, `removedCompleted`, `removedDeadLetter`, `mayHaveMore` |
 | `pull.served` | Once per served pull half, after all sections streamed | `clientId`, `subscriptions[]`: `{id, table, status, mode` (`bootstrap` \| `incremental` \| `none`)`, fromCursor, nextCursor, commits, changes, segments[]}`; each segment: `{mediaType` (`rows` \| `sqlite`)`, delivery` (`inline` \| `ref`)`, origin` (`built` \| `reused`)`, bytes, rows}` |
 | `segment.downloaded` | Every direct segment download (§5.5), success or failure | `segmentId`, `outcome` (`ok` \| `error`), `errorCode?`, `mediaType?`, `bytes?`, `durationMs` |
 | `blob.swept` | Every `sweepOrphanBlobs` pass (§5.9.2 orphan GC) | `partition`, `swept` (deleted count), `referenced` (keep-set size), `graceMs` |
@@ -325,10 +460,9 @@ exists) `partition` / `actorId`.
 
 ## Admin / console surface (`SyncularAdmin`)
 
-The operator-facing read surface over the server core. It is a module in
-this package — **not** a separate UI package — and adds **zero** wire
-protocol: SPEC.md says nothing about it, because authorization for these
-reads is entirely the host's. It delivers the 80% operator value (who's
+The operator-facing read surface over the server core lives in this package
+and adds **zero** wire protocol. Authorization for these reads is entirely the
+host's. It delivers the 80% operator value (who's
 connected, what's flowing,
 horizon health, the event tail) as a handful of read-only, partition-scoped,
 JSON-able queries.
@@ -367,6 +501,7 @@ by design:
 | `listClients(partition)` | Known clients: `clientId`, `actorId`, `cursor`, `lag` (commits not yet pulled: `maxCommitSeq − max(cursor, 0)`), `updatedAtMs`, `subscriptions[]`, and an `active` flag (cursor touched within the §4.6 active window). |
 | `clientDetail(partition, clientId, {eventLimit?})` | One client's drill-down: `{exists, client?, lease?, events}` — the record (with lag), its §7.3 lease when a lease store is wired, and its slice of the event tail. Answers "why is this client stale" in one read. |
 | `listCommits(partition, {afterSeq?, limit?, table?})` | Commit-log **metadata** (never payloads), newest first: `commitSeq`, `clientId`, `clientCommitId`, `actorId`, `createdAtMs`, `changeCount`, `tables[]`. |
+| `listReactions(partition, {statuses?, types?, limit?})` | Durable reaction lifecycle rows, newest first, including source commit, attempts, lease, completion, and bounded failure information. |
 | `inspectRow(partition, table, rowId)` | `{exists, serverVersion?, scopes?}` — current row version + stored scopes, payload **not** decoded. |
 | `scopeActivity(partition, {variable, value}, {limit?})` | Recent commits touching one scope key, via the §3.1 change-scope index (never a log scan). |
 | `horizonStatus(partition)` | `{maxCommitSeq, horizonSeq, retainedCommits, activeCursorFloor, recommendedHorizonSeq, recommendation}` — the horizon a prune pass would reach now (§4.6) + a coarse `up-to-date` / `prune-recommended`. |
@@ -413,6 +548,7 @@ app.route('/admin', routes);
 | `GET /clients` | `listClients` |
 | `GET /clients/:clientId?eventLimit` | `clientDetail` |
 | `GET /commits?afterSeq&limit&table` | `listCommits` |
+| `GET /reactions?status&type&limit` | `listReactions` |
 | `GET /rows/:table/:rowId` | `inspectRow` |
 | `GET /scope-activity?variable&value&limit` | `scopeActivity` |
 | `GET /horizon` | `horizonStatus` |
@@ -844,7 +980,8 @@ same table+scope during a storm, your TTL is shorter than the storm.
 
 ## Postgres storage (the production database path)
 
-`SqliteServerStorage` (bun:sqlite) is the dev-speed default. For
+`SqliteServerStorage` from `@syncular/server/sqlite` uses `bun:sqlite` or
+Node's built-in `node:sqlite`. For
 production, `PostgresServerStorage` implements the same `ServerStorage`
 contract against Postgres, with the inverted scope index carried through
 as **covering indexes** so scope fanout is an index range scan, never a

package/dist/admin.d.ts

@@ -4,9 +4,8 @@
  * `ServerStorage`, the optional segment/blob store stats, and an in-memory
  * event ring. It delivers the 80% operator value (who's connected, what's
  * flowing, horizon health, the event tail) as a handful of queries in the
- * server package — no separate
- * UI package, no framework, no wire-protocol surface (SPEC.md is untouched;
- * this is host surface, mirrored in the server README).
+ * server package — no separate UI package, no framework, and no wire-protocol
+ * surface. This host surface is mirrored in the server README.
  *
  * Nothing here is on the sync hot path. Every method is a plain read; the
  * additive optional storage/store methods it depends on are documented as
@@ -22,7 +21,7 @@ import type { LeaseRecord, LeaseStore } from './lease-store.js';
 import { type RetentionPolicy } from './prune.js';
 import { type ServerSchema } from './schema.js';
 import type { SegmentStore, SegmentStoreStats } from './segment-store.js';
-import type { CommitMetadata, ScopeCommitActivity, ServerStorage } from './storage.js';
+import type { CommitMetadata, ReactionStatus, ScopeCommitActivity, ServerStorage, StoredReaction } from './storage.js';
 /** A connected/known client as the console sees it (§4.5, §8.1). */
 export interface AdminClient {
     readonly clientId: string;
@@ -123,6 +122,11 @@ export interface AdminListCommitsOptions {
 export interface AdminScopeActivityOptions {
     readonly limit?: number;
 }
+export interface AdminListReactionsOptions {
+    readonly statuses?: readonly ReactionStatus[];
+    readonly types?: readonly string[];
+    readonly limit?: number;
+}
 export interface AdminStats {
     readonly segments?: SegmentStoreStats;
     readonly blobs?: BlobStoreStats;
@@ -171,6 +175,8 @@ export declare class SyncularAdmin {
     }): Promise<AdminClientDetail>;
     /** Commit-log metadata (no payloads), newest first. */
     listCommits(partition: string, options?: AdminListCommitsOptions): Promise<CommitMetadata[]>;
+    /** Pending, leased, completed, and dead-lettered durable reactions. */
+    listReactions(partition: string, options?: AdminListReactionsOptions): Promise<StoredReaction[]>;
     /**
      * Inspect a single row: current server_version, stored scopes, and the
      * blobIds it references (when the store tracks references). Payload bytes

package/dist/admin.js

@@ -3,6 +3,7 @@ import { DEFAULT_RETENTION } from './prune.js';
 import { compileSchema } from './schema.js';
 const DEFAULT_COMMIT_LIMIT = 50;
 const DEFAULT_SCOPE_LIMIT = 50;
+const DEFAULT_REACTION_LIMIT = 100;
 const DEFAULT_CLIENT_EVENT_LIMIT = 100;
 const DEFAULT_METRICS_WINDOW_MS = 5 * 60 * 1000;
 const DEFAULT_METRICS_BUCKETS = 30;
@@ -120,6 +121,15 @@ export class SyncularAdmin {
             ...(options.table !== undefined ? { table: options.table } : {}),
         });
     }
+    /** Pending, leased, completed, and dead-lettered durable reactions. */
+    async listReactions(partition, options = {}) {
+        const read = required(this.#storage.listReactions?.bind(this.#storage), 'storage');
+        return read(partition, {
+            limit: options.limit ?? DEFAULT_REACTION_LIMIT,
+            ...(options.statuses !== undefined ? { statuses: options.statuses } : {}),
+            ...(options.types !== undefined ? { types: options.types } : {}),
+        });
+    }
     /**
      * Inspect a single row: current server_version, stored scopes, and the
      * blobIds it references (when the store tracks references). Payload bytes

package/dist/authoritative-query.d.ts

@@ -0,0 +1,20 @@
+import type { CompiledTable } from './schema.js';
+import type { AuthoritativeQueryValue } from './storage.js';
+export interface PreparedAuthoritativeQuery {
+    readonly sql: string;
+    readonly params: readonly (AuthoritativeQueryValue | typeof PARTITION_BIND)[];
+}
+export interface BoundAuthoritativeQuery {
+    readonly sql: string;
+    readonly params: readonly AuthoritativeQueryValue[];
+}
+declare const PARTITION_BIND: unique symbol;
+/**
+ * Turn generated local SQL into a partition-local authoritative statement.
+ * Only relations declared by the generated descriptor are rewritten. Values
+ * remain parameters; request data is never interpolated into SQL.
+ */
+export declare function prepareAuthoritativeQuery(sql: string, params: readonly AuthoritativeQueryValue[], declaredTables: readonly string[], tables: ReadonlyMap<string, CompiledTable>): PreparedAuthoritativeQuery;
+export declare function bindAuthoritativePartition(prepared: PreparedAuthoritativeQuery, partition: string): BoundAuthoritativeQuery;
+export declare function postgresPlaceholders(sql: string): string;
+export {};

package/dist/authoritative-query.js

@@ -0,0 +1,184 @@
+import { quoteIdent, SYNC_PARTITION_COLUMN } from './relational-rows.js';
+const PARTITION_BIND = Symbol('syncular.authoritative_partition');
+const RESERVED_ALIAS = new Set([
+    'on',
+    'where',
+    'group',
+    'order',
+    'inner',
+    'left',
+    'right',
+    'full',
+    'outer',
+    'natural',
+    'join',
+    'cross',
+    'using',
+    'limit',
+    'having',
+]);
+const IDENT = '[A-Za-z_][A-Za-z0-9_]*';
+const TABLE_REF_RE = new RegExp(`\\b(FROM|(?:NATURAL\\s+)?(?:(?:LEFT|RIGHT|FULL)(?:\\s+OUTER)?|INNER|CROSS)?\\s*JOIN)\\s+((?:\\(\\s*)*)(${IDENT})(?:\\s+(?:AS\\s+)?((?!(?:${[...RESERVED_ALIAS].join('|')})\\b)${IDENT}))?`, 'gi');
+function protectedSqlEnd(sql, index) {
+    const char = sql[index];
+    const next = sql[index + 1];
+    if (char === "'" || char === '"' || char === '`') {
+        let end = index + 1;
+        while (end < sql.length) {
+            if (sql[end] === char && sql[end + 1] === char)
+                end += 2;
+            else if (sql[end] === char)
+                return end + 1;
+            else
+                end += 1;
+        }
+        return sql.length;
+    }
+    if (char === '[') {
+        const end = sql.indexOf(']', index + 1);
+        return end < 0 ? sql.length : end + 1;
+    }
+    if (char === '-' && next === '-') {
+        const end = sql.indexOf('\n', index);
+        return end < 0 ? sql.length : end;
+    }
+    if (char === '/' && next === '*') {
+        const end = sql.indexOf('*/', index + 2);
+        return end < 0 ? sql.length : end + 2;
+    }
+    return undefined;
+}
+function maskedSql(sql) {
+    let out = '';
+    let index = 0;
+    while (index < sql.length) {
+        const end = protectedSqlEnd(sql, index);
+        if (end === undefined)
+            out += sql[index];
+        else
+            out += sql.slice(index, end).replace(/[^\n]/g, ' ');
+        index = end ?? index + 1;
+    }
+    return out;
+}
+/**
+ * Turn generated local SQL into a partition-local authoritative statement.
+ * Only relations declared by the generated descriptor are rewritten. Values
+ * remain parameters; request data is never interpolated into SQL.
+ */
+export function prepareAuthoritativeQuery(sql, params, declaredTables, tables) {
+    if (maskedSql(sql).includes(';'))
+        throw new Error('registered query must be one SELECT');
+    const declared = new Set(declaredTables);
+    const masked = maskedSql(sql);
+    const replacements = [];
+    const found = new Set();
+    for (const match of masked.matchAll(TABLE_REF_RE)) {
+        const rawTable = match[3];
+        const table = tables.get(rawTable);
+        if (table === undefined)
+            continue;
+        if (!declared.has(table.name)) {
+            throw new Error('registered query table metadata does not match its SQL');
+        }
+        if (!table.materialize) {
+            throw new Error('registered query targets a non-materialized table');
+        }
+        let alias = match[4];
+        if (alias !== undefined && RESERVED_ALIAS.has(alias.toLowerCase())) {
+            alias = undefined;
+        }
+        const matchStart = match.index ?? 0;
+        const afterOperator = match[1].length;
+        const relative = match[0]
+            .toLowerCase()
+            .indexOf(rawTable.toLowerCase(), afterOperator);
+        const start = matchStart + relative;
+        const projection = table.columns.map((column) => quoteIdent(column.name));
+        replacements.push({
+            start,
+            end: start + rawTable.length,
+            text: `(SELECT ${projection.join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=/*syncular_partition*/?)${alias === undefined ? ` AS ${quoteIdent(table.name)}` : ''}`,
+        });
+        found.add(table.name);
+    }
+    if (found.size !== declared.size ||
+        [...declared].some((table) => !found.has(table))) {
+        throw new Error('registered query table metadata does not match its SQL');
+    }
+    let rewritten = sql;
+    for (const replacement of replacements.sort((left, right) => right.start - left.start)) {
+        rewritten =
+            rewritten.slice(0, replacement.start) +
+                replacement.text +
+                rewritten.slice(replacement.end);
+    }
+    const bound = [];
+    let anonymousIndex = 0;
+    let rendered = '';
+    for (let index = 0; index < rewritten.length; index += 1) {
+        if (rewritten.startsWith('/*syncular_partition*/?', index)) {
+            rendered += '?';
+            bound.push(PARTITION_BIND);
+            index += '/*syncular_partition*/?'.length - 1;
+            continue;
+        }
+        const protectedEnd = protectedSqlEnd(rewritten, index);
+        if (protectedEnd !== undefined) {
+            rendered += rewritten.slice(index, protectedEnd);
+            index = protectedEnd - 1;
+            continue;
+        }
+        const char = rewritten[index];
+        if (char !== '?') {
+            rendered += char;
+            continue;
+        }
+        let end = index + 1;
+        while (end < rewritten.length && /[0-9]/.test(rewritten[end])) {
+            end += 1;
+        }
+        const numbered = rewritten.slice(index + 1, end);
+        const parameterIndex = numbered.length > 0
+            ? Number.parseInt(numbered, 10) - 1
+            : anonymousIndex++;
+        if (numbered.length > 0) {
+            anonymousIndex = Math.max(anonymousIndex, parameterIndex + 1);
+        }
+        if (parameterIndex < 0 || parameterIndex >= params.length) {
+            throw new Error('registered query bind metadata does not match its SQL');
+        }
+        const value = params[parameterIndex];
+        if (value === undefined) {
+            throw new Error('registered query bind metadata does not match its SQL');
+        }
+        rendered += '?';
+        bound.push(value);
+        index = end - 1;
+    }
+    return { sql: rendered, params: bound };
+}
+export function bindAuthoritativePartition(prepared, partition) {
+    return {
+        sql: prepared.sql,
+        params: prepared.params.map((value) => value === PARTITION_BIND ? partition : value),
+    };
+}
+export function postgresPlaceholders(sql) {
+    let bind = 0;
+    let rendered = '';
+    for (let index = 0; index < sql.length; index += 1) {
+        const protectedEnd = protectedSqlEnd(sql, index);
+        if (protectedEnd !== undefined) {
+            rendered += sql.slice(index, protectedEnd);
+            index = protectedEnd - 1;
+        }
+        else if (sql[index] === '?') {
+            rendered += `$${++bind}`;
+        }
+        else {
+            rendered += sql[index];
+        }
+    }
+    return rendered;
+}

package/dist/context.d.ts

@@ -9,6 +9,7 @@ import type { BlobStore } from './blob-store.js';
 import type { CrdtMergerRegistry } from './crdt-merger.js';
 import type { SyncularServerEvents } from './events.js';
 import type { LeaseStore } from './lease-store.js';
+import type { AnyReactionPlanner } from './reactions.js';
 import type { ServerSchema } from './schema.js';
 import type { SegmentStore } from './segment-store.js';
 import type { BlobPresignConfig, BlobUploadPresignConfig, SegmentUrlConfig } from './signed-url.js';
@@ -17,6 +18,8 @@ import type { ServerStorage, StoredCommit } from './storage.js';
 import type { CommitValidator, ValidatorRegistry } from './validate.js';
 /** SSP2 body content type (§1.1). */
 export declare const SSP2_CONTENT_TYPE = "application/vnd.syncular.sync.v2";
+/** Internal idempotency namespace. Ordinary SSP2 client IDs cannot use it. */
+export declare const REMOTE_COMMAND_CLIENT_ID_PREFIX = "[\"remote-command\",";
 export interface ResolveScopesArgs {
     readonly partition: string;
     readonly actorId: string;
@@ -101,6 +104,12 @@ export interface SyncServerConfig {
      * commit-log/idempotency append. A throw rolls back the complete commit.
      */
     readonly commitValidator?: CommitValidator;
+    /**
+     * Pure durable-reaction planner. Runs once after candidate validation and
+     * before commit-log/idempotency append. Its bounded records are enqueued in
+     * the same transaction; handlers run later through `ReactionRunner`.
+     */
+    readonly reactionPlanner?: AnyReactionPlanner;
     readonly resolveScopes: ResolveScopes;
     /**
      * §7.3 auth leases. Absent ⇒ the feature is off: no `LEASE` frame is
@@ -139,7 +148,8 @@ export interface SyncServerConfig {
      * §5.3 sqlite-image builder, injected so the pull path never
      * statically imports `bun:sqlite`. Absent ⇒ the sqlite-image lane is off
      * (bit-2 clients are served the rows lane) — the Workers/edge posture. A
-     * Bun/Node host wires `buildSqliteImage` from `@syncular/server`.
+     * Bun or Node host wires `buildSqliteImage` from
+     * `@syncular/server/sqlite`.
      */
     readonly sqliteImageBuilder?: SqliteImageBuilder;
     readonly realtime?: RealtimeNotifier;

package/dist/context.js

@@ -1,5 +1,7 @@
 /** SSP2 body content type (§1.1). */
 export const SSP2_CONTENT_TYPE = 'application/vnd.syncular.sync.v2';
+/** Internal idempotency namespace. Ordinary SSP2 client IDs cannot use it. */
+export const REMOTE_COMMAND_CLIENT_ID_PREFIX = '["remote-command",';
 /**
  * Sentinel a resolver returns to signal a **live-authorization outage**
  * (§7.3.3): the live authority is unreachable, so the server SHOULD

package/dist/d1-storage.d.ts

@@ -1,5 +1,5 @@
 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 interface D1PreparedStatement {
     bind(...values: unknown[]): D1PreparedStatement;
     first<T = Record<string, unknown>>(): Promise<T | null>;
@@ -38,12 +38,21 @@ export declare class D1ServerStorage implements ServerStorage {
     ensureSchema(schema: CompiledSchema): Promise<void>;
     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[]>;