@syncular/server 0.15.45 → 0.15.46

package/dist/sqlite-storage.js

@@ -7,12 +7,39 @@
  * match against the stored scope map — never a log scan.
  */
 import { Database } from 'bun:sqlite';
+import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { collectCommitWindowPage, deserializePushResult, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
 import { isSqliteConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
+function toStoredReaction(record) {
+    return {
+        idempotencyKey: record.idempotency_key,
+        type: record.type,
+        version: record.version,
+        payload: JSON.parse(record.payload),
+        sourceClientId: record.source_client_id,
+        sourceClientCommitId: record.source_client_commit_id,
+        sourceCommitSeq: record.source_commit_seq,
+        createdAtMs: record.created_at_ms,
+        maxAttempts: record.max_attempts,
+        status: record.status,
+        attempts: record.attempts,
+        availableAtMs: record.available_at_ms,
+        ...(record.lease_owner !== null ? { leaseOwner: record.lease_owner } : {}),
+        ...(record.lease_expires_at_ms !== null
+            ? { leaseExpiresAtMs: record.lease_expires_at_ms }
+            : {}),
+        ...(record.completed_at_ms !== null
+            ? { completedAtMs: record.completed_at_ms }
+            : {}),
+        ...(record.last_failure !== null
+            ? { lastFailure: JSON.parse(record.last_failure) }
+            : {}),
+    };
+}
 class SqliteTransaction {
     #storage;
     #partition;
@@ -118,6 +145,17 @@ class SqliteTransaction {
             .query('INSERT OR IGNORE INTO sync_push_results(partition, client_id, client_commit_id, result) VALUES (?,?,?,?)')
             .run(this.#partition, clientId, clientCommitId, serializePushResult(result));
     }
+    async enqueueReactions(reactions) {
+        this.#assertOpen();
+        const statement = this.#storage.db.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 (?,?,?,?,?,?,?,?,?,?,'pending',0,?)`);
+        for (const reaction of reactions) {
+            statement.run(this.#partition, reaction.idempotencyKey, reaction.type, reaction.version, JSON.stringify(reaction.payload), reaction.sourceClientId, reaction.sourceClientCommitId, reaction.sourceCommitSeq, reaction.createdAtMs, reaction.createdAtMs, reaction.maxAttempts);
+        }
+    }
     async commit() {
         this.#assertOpen();
         try {
@@ -161,6 +199,20 @@ export class SqliteServerStorage {
     /** Set by `ensureSchema`: app-table lookup for the relational row store. */
     #tables;
     #schemaVersion;
+    async #serializeReactionWrite(operation) {
+        const previous = this.#transactionTail;
+        let release;
+        this.#transactionTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return operation();
+        }
+        finally {
+            release();
+        }
+    }
     constructor(db = ':memory:') {
         this.db = typeof db === 'string' ? new Database(db) : db;
         this.db.exec(SQLITE_DDL);
@@ -310,6 +362,40 @@ export class SqliteServerStorage {
             .get(partition);
         return row?.max_commit_seq ?? 0;
     }
+    async queryAuthoritative(partition, query) {
+        if (this.#tables === undefined) {
+            throw new Error('ensureSchema(schema) must run before registered queries');
+        }
+        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.sql, query.params, query.tables, this.#tables), partition);
+        const previous = this.#transactionTail;
+        let release;
+        this.#transactionTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        let open = false;
+        try {
+            this.db.exec('BEGIN');
+            open = true;
+            const rows = this.db
+                .query(prepared.sql)
+                .all(...prepared.params);
+            const cursor = this.db
+                .query('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
+                .get(partition);
+            this.db.exec('COMMIT');
+            open = false;
+            return { rows, maxCommitSeq: cursor?.max_commit_seq ?? 0 };
+        }
+        catch (error) {
+            if (open)
+                this.db.exec('ROLLBACK');
+            throw error;
+        }
+        finally {
+            release();
+        }
+    }
     async getHorizonSeq(partition) {
         const row = this.db
             .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
@@ -361,6 +447,135 @@ export class SqliteServerStorage {
             throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
         }
     }
+    async claimReactions(partition, query) {
+        if (query.types.length === 0 || query.limit <= 0)
+            return [];
+        return this.#serializeReactionWrite(() => {
+            const typeParams = query.types.map(() => '?').join(',');
+            const records = this.db
+                .query(`UPDATE sync_reactions
+            SET status='leased', attempts=attempts+1,
+                lease_owner=?, lease_expires_at_ms=?, completed_at_ms=NULL
+          WHERE (partition, idempotency_key) IN (
+            SELECT partition, idempotency_key
+              FROM sync_reactions
+             WHERE partition=? AND type IN (${typeParams})
+               AND ((status='pending' AND available_at_ms<=?)
+                 OR (status='leased' AND lease_expires_at_ms<=?))
+             ORDER BY CASE WHEN status='leased' THEN lease_expires_at_ms
+                           ELSE available_at_ms END,
+                      created_at_ms, idempotency_key
+             LIMIT ?
+          )
+        RETURNING *`)
+                .all(query.leaseOwner, Math.min(Number.MAX_SAFE_INTEGER, query.nowMs + query.leaseDurationMs), partition, ...query.types, query.nowMs, query.nowMs, query.limit);
+            return records
+                .map(toStoredReaction)
+                .sort((a, b) => a.createdAtMs - b.createdAtMs ||
+                a.idempotencyKey.localeCompare(b.idempotencyKey));
+        });
+    }
+    async completeReaction(partition, idempotencyKey, leaseOwner, completedAtMs) {
+        return this.#serializeReactionWrite(() => {
+            const result = this.db
+                .query(`UPDATE sync_reactions
+            SET status='completed', completed_at_ms=?,
+                lease_owner=NULL, lease_expires_at_ms=NULL
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?`)
+                .run(completedAtMs, partition, idempotencyKey, leaseOwner);
+            return Number(result.changes) === 1;
+        });
+    }
+    async extendReactionLease(partition, idempotencyKey, leaseOwner, leaseExpiresAtMs) {
+        return this.#serializeReactionWrite(() => {
+            const result = this.db
+                .query(`UPDATE sync_reactions SET lease_expires_at_ms=?
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?`)
+                .run(leaseExpiresAtMs, partition, idempotencyKey, leaseOwner);
+            return Number(result.changes) === 1;
+        });
+    }
+    async failReaction(partition, idempotencyKey, update) {
+        const retry = update.retryAtMs !== undefined;
+        return this.#serializeReactionWrite(() => {
+            const result = this.db
+                .query(`UPDATE sync_reactions
+            SET status=?, available_at_ms=?, last_failure=?,
+                lease_owner=NULL, lease_expires_at_ms=NULL
+          WHERE partition=? AND idempotency_key=?
+            AND status='leased' AND lease_owner=?`)
+                .run(retry ? 'pending' : 'dead-letter', update.retryAtMs ?? update.failure.atMs, JSON.stringify(update.failure), partition, idempotencyKey, update.leaseOwner);
+            return Number(result.changes) === 1;
+        });
+    }
+    async retryReaction(partition, idempotencyKey, nowMs) {
+        return this.#serializeReactionWrite(() => {
+            const result = this.db
+                .query(`UPDATE sync_reactions
+            SET status='pending', attempts=0, available_at_ms=?,
+                last_failure=NULL, lease_owner=NULL, lease_expires_at_ms=NULL,
+                completed_at_ms=NULL
+          WHERE partition=? AND idempotency_key=? AND status='dead-letter'`)
+                .run(nowMs, partition, idempotencyKey);
+            return Number(result.changes) === 1;
+        });
+    }
+    async getReaction(partition, idempotencyKey) {
+        const record = this.db
+            .query('SELECT * FROM sync_reactions WHERE partition=? AND idempotency_key=?')
+            .get(partition, idempotencyKey);
+        return record === null ? undefined : toStoredReaction(record);
+    }
+    async listReactions(partition, query) {
+        const where = ['partition=?'];
+        const params = [partition];
+        if (query.statuses !== undefined && query.statuses.length > 0) {
+            where.push(`status IN (${query.statuses.map(() => '?').join(',')})`);
+            params.push(...query.statuses);
+        }
+        if (query.types !== undefined && query.types.length > 0) {
+            where.push(`type IN (${query.types.map(() => '?').join(',')})`);
+            params.push(...query.types);
+        }
+        params.push(query.limit);
+        const records = this.db
+            .query(`SELECT * FROM sync_reactions WHERE ${where.join(' AND ')}
+          ORDER BY created_at_ms DESC, idempotency_key DESC LIMIT ?`)
+            .all(...params);
+        return records.map(toStoredReaction);
+    }
+    async pruneReactions(partition, query) {
+        if (query.limit <= 0)
+            return { completed: 0, deadLetter: 0 };
+        return this.#serializeReactionWrite(() => {
+            const records = this.db
+                .query(`DELETE FROM sync_reactions
+            WHERE partition=? AND idempotency_key IN (
+              SELECT idempotency_key FROM sync_reactions
+               WHERE partition=?
+                 AND ((status='completed' AND completed_at_ms IS NOT NULL
+                       AND completed_at_ms<?)
+                   OR (status='dead-letter' AND available_at_ms<?))
+               ORDER BY CASE WHEN status='completed' THEN completed_at_ms
+                             ELSE available_at_ms END,
+                        idempotency_key
+               LIMIT ?
+            )
+              AND ((status='completed' AND completed_at_ms IS NOT NULL
+                    AND completed_at_ms<?)
+                OR (status='dead-letter' AND available_at_ms<?))
+          RETURNING status`)
+                .all(partition, partition, query.completedBeforeMs, query.deadLetterBeforeMs, query.limit, query.completedBeforeMs, query.deadLetterBeforeMs);
+            return {
+                completed: records.filter((record) => record.status === 'completed')
+                    .length,
+                deadLetter: records.filter((record) => record.status === 'dead-letter')
+                    .length,
+            };
+        });
+    }
     async readCommitWindow(partition, query) {
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];

package/dist/storage.d.ts

@@ -59,6 +59,71 @@ export interface StoredCommit {
     readonly actorId: string;
     readonly changes: readonly StoredChange[];
 }
+/** JSON values accepted by the durable reaction payload/failure store. */
+export type DurableJsonValue = null | boolean | number | string | readonly DurableJsonValue[] | {
+    readonly [key: string]: DurableJsonValue;
+};
+export type ReactionStatus = 'pending' | 'leased' | 'completed' | 'dead-letter';
+export interface ReactionFailure {
+    /** Stable application or Syncular error identity. */
+    readonly code: string;
+    readonly atMs: number;
+    /** Bounded JSON metadata. Diagnostic exception text is never persisted. */
+    readonly details?: {
+        readonly [key: string]: DurableJsonValue;
+    };
+}
+/** A validated reaction row written with its source commit. */
+export interface NewReaction {
+    readonly idempotencyKey: string;
+    readonly type: string;
+    readonly version: number;
+    readonly payload: DurableJsonValue;
+    readonly sourceClientId: string;
+    readonly sourceClientCommitId: string;
+    readonly sourceCommitSeq: number;
+    readonly createdAtMs: number;
+    readonly maxAttempts: number;
+}
+/** Durable reaction state returned to workers and administrative readers. */
+export interface StoredReaction extends NewReaction {
+    readonly status: ReactionStatus;
+    /** Incremented atomically when a worker claims the reaction. */
+    readonly attempts: number;
+    readonly availableAtMs: number;
+    readonly leaseOwner?: string;
+    readonly leaseExpiresAtMs?: number;
+    readonly completedAtMs?: number;
+    readonly lastFailure?: ReactionFailure;
+}
+export interface ReactionClaimQuery {
+    /** Opaque token unique to this claim operation. */
+    readonly leaseOwner: string;
+    readonly types: readonly string[];
+    readonly nowMs: number;
+    readonly leaseDurationMs: number;
+    readonly limit: number;
+}
+export interface ReactionListQuery {
+    readonly statuses?: readonly ReactionStatus[];
+    readonly types?: readonly string[];
+    readonly limit: number;
+}
+export interface ReactionFailureUpdate {
+    readonly leaseOwner: string;
+    readonly failure: ReactionFailure;
+    /** Present for retry; absent moves the row to the dead-letter state. */
+    readonly retryAtMs?: number;
+}
+export interface ReactionPruneQuery {
+    readonly completedBeforeMs: number;
+    readonly deadLetterBeforeMs: number;
+    readonly limit: number;
+}
+export interface PrunedReactionCounts {
+    readonly completed: number;
+    readonly deadLetter: number;
+}
 /** Persisted push outcome for idempotent replay (§2.3, §6.3). */
 export interface StoredPushResult {
     readonly status: 'applied' | 'rejected';
@@ -166,6 +231,20 @@ export interface ScopeActivityQuery {
     readonly value: string;
     readonly limit: number;
 }
+/** A registered SELECT executed against the authoritative row projection. */
+export type AuthoritativeQueryValue = string | number | bigint | boolean | Uint8Array | null;
+export interface AuthoritativeQueryRequest {
+    /** Generated, positional SQLite-family SQL. It never comes from the request. */
+    readonly sql: string;
+    readonly params: readonly AuthoritativeQueryValue[];
+    /** Generated dependency set, used to validate and partition every relation. */
+    readonly tables: readonly string[];
+}
+/** One transactionally consistent authoritative query snapshot. */
+export interface AuthoritativeQueryResult {
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly maxCommitSeq: number;
+}
 /**
  * One transaction per push commit (§6.4): all row writes, the appended
  * commit (with its scope-index entries), and the idempotency record either
@@ -222,6 +301,12 @@ export interface StorageTransaction {
     deleteRow(table: string, rowId: string): Promise<void>;
     /** Allocates the next per-partition commitSeq and appends the commit. */
     appendCommit(commit: NewCommit): Promise<number>;
+    /**
+     * Persist reaction rows in this authoritative transaction. Required when
+     * the host configures a reaction planner. Reactions survive commit-log
+     * pruning because they live outside the commit/change tables.
+     */
+    enqueueReactions?(reactions: readonly NewReaction[]): Promise<void>;
     /**
      * Persist an idempotency outcome only when the key is still absent. The
      * first writer wins; callers read the canonical value after commit.
@@ -272,6 +357,24 @@ export interface ServerStorage {
      * when a persisted result exists but cannot be read (§6.3).
      */
     getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
+    /**
+     * Atomically lease due or expired-lease reactions for one worker. Optional
+     * for compatibility with custom storages; reaction runners fail closed when
+     * any lifecycle method is absent.
+     */
+    claimReactions?(partition: string, query: ReactionClaimQuery): Promise<StoredReaction[]>;
+    /** Acknowledge only while `leaseOwner` still owns the lease. */
+    completeReaction?(partition: string, idempotencyKey: string, leaseOwner: string, completedAtMs: number): Promise<boolean>;
+    /** Extend only while `leaseOwner` still owns the active lease. */
+    extendReactionLease?(partition: string, idempotencyKey: string, leaseOwner: string, leaseExpiresAtMs: number): Promise<boolean>;
+    /** Retry or dead-letter only while `leaseOwner` still owns the lease. */
+    failReaction?(partition: string, idempotencyKey: string, update: ReactionFailureUpdate): Promise<boolean>;
+    /** Reset a dead-lettered row for an explicit operator retry. */
+    retryReaction?(partition: string, idempotencyKey: string, nowMs: number): Promise<boolean>;
+    getReaction?(partition: string, idempotencyKey: string): Promise<StoredReaction | undefined>;
+    listReactions?(partition: string, query: ReactionListQuery): Promise<StoredReaction[]>;
+    /** Delete a bounded set of aged terminal rows. Never deletes active work. */
+    pruneReactions?(partition: string, query: ReactionPruneQuery): Promise<PrunedReactionCounts>;
     /**
      * Matching commits in the window, oldest first, each carrying only its
      * matching changes for `table`. Stops once accumulated matching changes
@@ -280,6 +383,12 @@ export interface ServerStorage {
     readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
     /** Scope-filtered snapshot scan, ordered by rowId (bootstrap paging). */
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
+    /**
+     * Optional registered-query capability. The implementation MUST replace
+     * every generated app-table relation with a partition-filtered relation and
+     * return rows plus maxCommitSeq from one consistent database snapshot.
+     */
+    queryAuthoritative?(partition: string, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
     /**
      * Optional trusted-host exact lookup through a declared relational index.
      * This capability is outside client scope/subscription authorization and

package/dist/validate.js

@@ -25,6 +25,7 @@ import { normalizeRejectionDetails, } from '@syncular/core';
 export const RESERVED_VALIDATION_CODE_PREFIXES = [
     'sync.',
     'blob.',
+    'operation.',
     'presence.',
     'client.',
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.15.45",
+  "version": "0.15.46",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -53,7 +53,7 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/core": "0.15.45"
+    "@syncular/core": "0.15.46"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/admin.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
@@ -25,8 +24,10 @@ import type { SegmentStore, SegmentStoreStats } from './segment-store';
 import type {
   ClientRecord,
   CommitMetadata,
+  ReactionStatus,
   ScopeCommitActivity,
   ServerStorage,
+  StoredReaction,
 } from './storage';
 
 /** A connected/known client as the console sees it (§4.5, §8.1). */
@@ -137,6 +138,12 @@ 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;
@@ -164,6 +171,7 @@ export interface SyncularAdminOptions {
 
 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;
@@ -313,6 +321,22 @@ export class SyncularAdmin {
     });
   }
 
+  /** Pending, leased, completed, and dead-lettered durable reactions. */
+  async listReactions(
+    partition: string,
+    options: AdminListReactionsOptions = {},
+  ): Promise<StoredReaction[]> {
+    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