@syncular/server 0.8.0 → 0.10.0

package/dist/sqlite-storage.js

@@ -15,6 +15,7 @@ class SqliteTransaction {
     #storage;
     #partition;
     #open = true;
+    #commitValidationSavepoint = false;
     constructor(storage, partition) {
         this.#storage = storage;
         this.#partition = partition;
@@ -28,6 +29,27 @@ class SqliteTransaction {
         this.#assertOpen();
         return this.#storage.getRow(this.#partition, table, rowId);
     }
+    scanRows(query) {
+        this.#assertOpen();
+        return this.#storage.scanRows(this.#partition, query);
+    }
+    async lockPartitionForCommitValidation() {
+        this.#assertOpen();
+        // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
+        this.#storage.db.exec('SAVEPOINT syncular_commit_validation_candidate');
+        this.#commitValidationSavepoint = true;
+    }
+    async commitRejectedPushResult(clientId, clientCommitId, result) {
+        this.#assertOpen();
+        if (!this.#commitValidationSavepoint) {
+            throw new Error('whole-commit rejection requires its validation savepoint');
+        }
+        this.#storage.db.exec('ROLLBACK TO SAVEPOINT syncular_commit_validation_candidate');
+        this.#storage.db.exec('RELEASE SAVEPOINT syncular_commit_validation_candidate');
+        this.#commitValidationSavepoint = false;
+        await this.putPushResult(clientId, clientCommitId, result);
+        await this.commit();
+    }
     async upsertRow(table, row) {
         this.#assertOpen();
         this.#storage.writeRow(this.#partition, table, row);

package/dist/storage.d.ts

@@ -150,6 +150,24 @@ export interface ScopeActivityQuery {
  */
 export interface StorageTransaction {
     getRow(table: string, rowId: string): Promise<StoredRow | undefined>;
+    /**
+     * Optional candidate-state scan used only by whole-commit validation.
+     * In-tree SQLite/Postgres/D1 backends implement it with read-your-own-writes
+     * semantics. A custom backend may omit it until `commitValidator` is used.
+     */
+    scanRows?(query: RowScanQuery): Promise<StoredRow[]>;
+    /**
+     * Serialize candidate-state validation for this partition before any row
+     * read/write. Required at runtime when `commitValidator` is configured.
+     */
+    lockPartitionForCommitValidation?(): Promise<void>;
+    /**
+     * §6.8 rejection finalization while the validation serialization lock is
+     * still held: discard every candidate write, persist the rejected
+     * idempotency result, and finish the transaction atomically. Required when
+     * `commitValidator` is configured so a concurrent duplicate cannot rerun it.
+     */
+    commitRejectedPushResult?(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<void>;
     upsertRow(table: string, row: StoredRow): Promise<void>;
     deleteRow(table: string, rowId: string): Promise<void>;
     /** Allocates the next per-partition commitSeq and appends the commit. */

package/dist/validate.d.ts

@@ -13,7 +13,7 @@
  * path pays only an `undefined` check per operation and builds no context
  * object — zero cost, the events-seam discipline.
  */
-import type { RowColumn, RowValue } from '@syncular/core';
+import { type RejectionDetails, type RowColumn, type RowValue, type ScopeMap } from '@syncular/core';
 /**
  * §6.7 reserved code prefixes. A host validator code MUST NOT start with
  * any of these: they namespace the protocol's own error families (§10.2)
@@ -49,6 +49,52 @@ export interface ValidateOperation {
     /** The currently-stored row (update/delete), keyed by column name; undefined on insert. */
     readonly stored: ValidateRow | undefined;
 }
+/**
+ * One authorized, decoded operation presented to the whole-commit validator.
+ * `row` is the final candidate row after scope stripping and CRDT merge;
+ * `stored` is the state observed immediately before this operation. Multiple
+ * operations targeting one row therefore retain their sequential evidence.
+ */
+export interface ValidateCommitOperation extends ValidateOperation {
+    readonly opIndex: number;
+    readonly storedServerVersion?: number;
+    readonly nextServerVersion?: number;
+}
+/** One candidate-state row read from inside the still-open commit transaction. */
+export interface CommitValidationRow {
+    readonly row: ValidateRow;
+    readonly serverVersion: number;
+}
+export interface CommitValidationScanInput {
+    readonly table: string;
+    /** Exact scope filter, using the same AND-across-keys semantics as sync. */
+    readonly scopeFilter: ScopeMap;
+    readonly afterRowId?: string | null;
+    /** Bounded per call by the server to 1..1,000; defaults to 100. */
+    readonly limit?: number;
+}
+/**
+ * Candidate-state reads bound to the same storage transaction as the commit.
+ * Reads observe every staged sibling operation and no uncommitted competing
+ * transaction when the storage's commit-validation lock contract is honored.
+ */
+export interface CommitValidationReader {
+    getRow(table: string, rowId: string): Promise<CommitValidationRow | undefined>;
+    scanRows(input: CommitValidationScanInput): Promise<CommitValidationRow[]>;
+}
+export interface ValidateCommitInput {
+    readonly clientId: string;
+    readonly clientCommitId: string;
+    readonly actorId: string;
+    readonly partition: string;
+    readonly operations: readonly ValidateCommitOperation[];
+    readonly read: CommitValidationReader;
+}
+/**
+ * Runs once after every operation passed protocol/scope/row validation and was
+ * staged, but before commit-log/idempotency append and transaction commit.
+ */
+export type CommitValidator = (input: ValidateCommitInput) => void | Promise<void>;
 /** Ambient context a validator may consult (§6.7). */
 export interface ValidateContext {
     /** Host-authenticated actor (§1.1) performing the write. */
@@ -77,7 +123,21 @@ export type ValidatorRegistry = Readonly<Record<string, Validator>>;
 export declare class ValidationRejection extends Error {
     readonly name = "ValidationRejection";
     readonly code: string;
-    constructor(code: string, message?: string);
+    /**
+     * Bounded code-like metadata explicitly safe to replicate to authorized
+     * clients. Never place diagnostic prose, secrets, or clinical values here.
+     */
+    readonly details: RejectionDetails | undefined;
+    constructor(code: string, message?: string, details?: RejectionDetails);
+}
+/**
+ * A whole-commit rejection attributed to one operation for the existing
+ * per-operation PUSH_RESULT envelope. The validator may still describe
+ * multiple affected fields in `details.fieldPaths`.
+ */
+export declare class CommitValidationRejection extends ValidationRejection {
+    readonly opIndex: number;
+    constructor(opIndex: number, code: string, message?: string, details?: RejectionDetails);
 }
 /** Build the column-keyed row object a validator inspects (§6.7). */
 export declare function toValidateRow(columns: readonly RowColumn[], values: readonly RowValue[]): ValidateRow;

package/dist/validate.js

@@ -1,3 +1,19 @@
+/**
+ * Server-side write-validation hooks (SPEC.md §6.7).
+ *
+ * An optional per-table `validate` callback that runs on push, AFTER the
+ * row-codec decode (§6.1) and the §3.4 scope authorization, INSIDE the
+ * commit transaction, once per operation. It is the seam for business
+ * rules that scopes cannot express ("title ≤ 200 chars", "amount ≥ 0",
+ * "status ∈ {…}"). A throw (or rejected promise) rejects the whole commit
+ * atomically (§6.4) with a host-defined code the client surfaces unchanged
+ * in its rejection record (§6.3).
+ *
+ * The feature is OFF by default (no `validators` on the config): the push
+ * path pays only an `undefined` check per operation and builds no context
+ * object — zero cost, the events-seam discipline.
+ */
+import { normalizeRejectionDetails, } from '@syncular/core';
 /**
  * §6.7 reserved code prefixes. A host validator code MUST NOT start with
  * any of these: they namespace the protocol's own error families (§10.2)
@@ -21,7 +37,12 @@ export const RESERVED_VALIDATION_CODE_PREFIXES = [
 export class ValidationRejection extends Error {
     name = 'ValidationRejection';
     code;
-    constructor(code, message) {
+    /**
+     * Bounded code-like metadata explicitly safe to replicate to authorized
+     * clients. Never place diagnostic prose, secrets, or clinical values here.
+     */
+    details;
+    constructor(code, message, details) {
         super(message ?? code);
         if (code.length === 0) {
             throw new Error('ValidationRejection code must be non-empty (§6.7)');
@@ -32,6 +53,23 @@ export class ValidationRejection extends Error {
             }
         }
         this.code = code;
+        this.details =
+            details === undefined ? undefined : normalizeRejectionDetails(details);
+    }
+}
+/**
+ * A whole-commit rejection attributed to one operation for the existing
+ * per-operation PUSH_RESULT envelope. The validator may still describe
+ * multiple affected fields in `details.fieldPaths`.
+ */
+export class CommitValidationRejection extends ValidationRejection {
+    opIndex;
+    constructor(opIndex, code, message, details) {
+        super(code, message, details);
+        this.opIndex = opIndex;
+        if (!Number.isSafeInteger(opIndex) || opIndex < 0) {
+            throw new Error('CommitValidationRejection opIndex must be a non-negative safe integer');
+        }
     }
 }
 /** Build the column-keyed row object a validator inspects (§6.7). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "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.8.0"
+    "@syncular/core": "0.10.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/context.ts

@@ -18,7 +18,7 @@ import type {
 } from './signed-url';
 import type { SqliteImageBuilder } from './sqlite-image';
 import type { ServerStorage, StoredCommit } from './storage';
-import type { ValidatorRegistry } from './validate';
+import type { CommitValidator, ValidatorRegistry } from './validate';
 
 /** SSP2 body content type (§1.1). */
 export const SSP2_CONTENT_TYPE = 'application/vnd.syncular.sync.v2';
@@ -112,6 +112,13 @@ export interface SyncServerConfig {
    * process, never on the wire.
    */
   readonly validators?: ValidatorRegistry;
+  /**
+   * §6.8 whole-commit validator. When present, the storage serializes this
+   * partition before operation reads/writes, then invokes the callback once
+   * over every staged decoded operation and candidate-state reader before
+   * commit-log/idempotency append. A throw rolls back the complete commit.
+   */
+  readonly commitValidator?: CommitValidator;
   readonly resolveScopes: ResolveScopes;
   /**
    * §7.3 auth leases. Absent ⇒ the feature is off: no `LEASE` frame is

package/src/frame-bytes.ts

@@ -11,6 +11,7 @@
 import {
   encodeMessage,
   PROTOCOL_WIRE_VERSION,
+  type PushResultFrame,
   type RespHeaderFrame,
   type ResponseFrame,
   type SubEndFrame,
@@ -54,6 +55,21 @@ function wrapperFor(frame: ResponseFrame): {
     case 'ERROR':
     case 'UNKNOWN':
       return { frames: [STUB_HEADER, frame], index: 1 };
+    case 'PUSH_RESULT_DETAILS': {
+      const result: PushResultFrame = {
+        type: 'PUSH_RESULT',
+        clientCommitId: frame.clientCommitId,
+        status: 'rejected',
+        results: frame.entries.map((entry) => ({
+          opIndex: entry.opIndex,
+          status: 'error',
+          code: 'sync.constraint_violation',
+          message: '',
+          retryable: false,
+        })),
+      };
+      return { frames: [STUB_HEADER, result, frame], index: 2 };
+    }
     case 'SUB_START':
       return { frames: [STUB_HEADER, frame, STUB_SUB_END], index: 1 };
     case 'SUB_END':

package/src/handler.ts

@@ -14,6 +14,7 @@ import {
   decodeMessage,
   type PullHeaderFrame,
   type PushCommitFrame,
+  type PushResultDetailsFrame,
   type PushResultFrame,
   type ReqHeaderFrame,
   type RequestMessage,
@@ -316,6 +317,23 @@ interface RequestReport {
   errorCode?: string;
 }
 
+function pushResultDetailsFrame(
+  frame: PushResultFrame,
+): PushResultDetailsFrame | undefined {
+  const entries = frame.results.flatMap((result) =>
+    result.status === 'error' && result.details !== undefined
+      ? [{ opIndex: result.opIndex, details: result.details }]
+      : [],
+  );
+  return entries.length === 0
+    ? undefined
+    : {
+        type: 'PUSH_RESULT_DETAILS',
+        clientCommitId: frame.clientCommitId,
+        entries,
+      };
+}
+
 function emitPushEvent(
   events: SyncularServerEvents,
   ctx: SyncRequestContext,
@@ -416,6 +434,8 @@ async function* streamResponse(
         emitPushEvent(events, ctx, plan.header.clientId, push, frame);
       }
       yield encodeResponseFrame(frame);
+      const details = pushResultDetailsFrame(frame);
+      if (details !== undefined) yield encodeResponseFrame(details);
     }
 
     // Pull half (§4): subscriptions echoed in request order.

package/src/postgres-storage.ts

@@ -165,6 +165,7 @@ interface SerializedResult {
   serverVersion?: number;
   serverRow?: string;
   retryable?: boolean;
+  details?: import('@syncular/core').RejectionDetails;
 }
 
 function toBase64(bytes: Uint8Array): string {
@@ -201,6 +202,7 @@ function serializePushResult(result: StoredPushResult): unknown {
           code: record.code,
           message: record.message,
           retryable: record.retryable,
+          ...(record.details !== undefined ? { details: record.details } : {}),
         };
       }
       return { opIndex: record.opIndex, status: record.status };
@@ -232,6 +234,7 @@ function deserializePushResult(value: unknown): StoredPushResult {
         code: record.code ?? '',
         message: record.message ?? '',
         retryable: record.retryable ?? false,
+        ...(record.details !== undefined ? { details: record.details } : {}),
       };
     }
     return { opIndex: record.opIndex, status: 'applied' };
@@ -393,6 +396,7 @@ class PostgresTransaction implements StorageTransaction {
   #partition: string;
   #resolveTable: (name: string) => CompiledTable;
   #open = true;
+  #commitValidationSavepoint = false;
   /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
   #resolve: () => void;
   #reject: (error: unknown) => void;
@@ -425,6 +429,81 @@ class PostgresTransaction implements StorageTransaction {
     );
   }
 
+  async scanRows(query: RowScanQuery): Promise<StoredRow[]> {
+    this.#assertOpen();
+    const variables = Object.keys(query.scopeFilter).sort();
+    const firstVariable = variables[0];
+    if (firstVariable === undefined) return [];
+    const firstValues = query.scopeFilter[firstVariable] ?? [];
+    if (firstValues.length === 0) return [];
+    const sql = scanRowPageSql(
+      this.#resolveTable(query.table),
+      firstValues.length,
+      'postgres',
+    );
+    const rows: StoredRow[] = [];
+    let afterRowId = query.afterRowId ?? '';
+    const batchSize = Math.max(64, query.limit);
+    while (rows.length < query.limit) {
+      const { rows: records } = await this.#client.query<RowRecord>(sql, [
+        this.#partition,
+        query.table,
+        firstVariable,
+        ...firstValues,
+        afterRowId,
+        batchSize,
+      ]);
+      if (records.length === 0) break;
+      for (const record of records) {
+        afterRowId = record.row_id;
+        if (record.payload === null || record.payload === undefined) continue;
+        const stored = toStoredRow(record);
+        if (!matchesEffective(stored.scopes, query.scopeFilter)) continue;
+        rows.push(stored);
+        if (rows.length >= query.limit) break;
+      }
+      if (records.length < batchSize) break;
+    }
+    return rows;
+  }
+
+  async lockPartitionForCommitValidation(): Promise<void> {
+    this.#assertOpen();
+    await this.#client.query(
+      `INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 0)
+       ON CONFLICT (partition) DO NOTHING`,
+      [this.#partition],
+    );
+    await this.#client.query(
+      'SELECT max_commit_seq FROM sync_partitions WHERE partition=$1 FOR UPDATE',
+      [this.#partition],
+    );
+    await this.#client.query('SAVEPOINT syncular_commit_validation_candidate');
+    this.#commitValidationSavepoint = true;
+  }
+
+  async commitRejectedPushResult(
+    clientId: string,
+    clientCommitId: string,
+    result: StoredPushResult,
+  ): Promise<void> {
+    this.#assertOpen();
+    if (!this.#commitValidationSavepoint) {
+      throw new Error(
+        'whole-commit rejection requires its validation savepoint',
+      );
+    }
+    await this.#client.query(
+      'ROLLBACK TO SAVEPOINT syncular_commit_validation_candidate',
+    );
+    await this.#client.query(
+      'RELEASE SAVEPOINT syncular_commit_validation_candidate',
+    );
+    this.#commitValidationSavepoint = false;
+    await this.putPushResult(clientId, clientCommitId, result);
+    await this.commit();
+  }
+
   async upsertRow(table: string, row: StoredRow): Promise<void> {
     this.#assertOpen();
     await writeRowOn(