@syncular/server 0.7.0 → 0.9.0

package/README.md

@@ -60,6 +60,55 @@ done by a binding of the core or by in-database fanout — a relay would add a
 hop, a second protocol surface, and a managed dependency for zero capability
 the core lacks.
 
+## Write validators and recovery metadata
+
+`validators` is the server-authoritative seam for row business rules that
+scope grants cannot express. A validator runs after row decode and scope
+authorization, inside the commit transaction, for HTTP and WebSocket sync
+rounds alike. Throw `ValidationRejection` for a deliberate host rejection:
+
+```ts
+import {
+  ValidationRejection,
+  type SyncServerConfig,
+} from '@syncular/server';
+
+const config: SyncServerConfig = {
+  schema,
+  storage,
+  segments,
+  resolveScopes,
+  validators: {
+    surgeries: ({ row }) => {
+      if (typeof row?.duration_minutes === 'number' && row.duration_minutes < 5) {
+        throw new ValidationRejection(
+          'surgery.duration_too_short',
+          'diagnostic only',
+          {
+            fieldPaths: ['duration_minutes'],
+            reason: 'below_minimum',
+            requiredAction: 'edit_fields',
+            references: { minimum_minutes: '5' },
+          },
+        );
+      }
+    },
+  },
+};
+```
+
+The third argument is optional. When supplied, Syncular validates and
+normalizes a bounded `RejectionDetails` object and persists it with the
+idempotency result. Its values replicate to the authorized client, so include
+only non-sensitive identifiers that the host explicitly approves for recovery
+UI. Unknown members, free-form tokens, malformed paths, and over-limit data
+fail at construction. Diagnostic prose stays in `message`; apps should map
+the stable code/details to localized copy instead of displaying that message.
+
+Validators are per-operation. They do not make multi-row or multi-table
+invariants atomic; those require a server-authoritative command or a future
+whole-commit validation seam. A validator must not mutate the row it receives.
+
 ## Structured events (the ops seam)
 
 One optional interface, `SyncularServerEvents`, carries every

package/dist/frame-bytes.js

@@ -39,6 +39,21 @@ function wrapperFor(frame) {
         case 'ERROR':
         case 'UNKNOWN':
             return { frames: [STUB_HEADER, frame], index: 1 };
+        case 'PUSH_RESULT_DETAILS': {
+            const result = {
+                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/dist/handler.js

@@ -187,6 +187,18 @@ async function planRequest(request, ctx, schema) {
         leaseToEmit,
     };
 }
+function pushResultDetailsFrame(frame) {
+    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, ctx, clientId, push, frame) {
     const base = {
         atMs: clockOf(ctx)(),
@@ -269,6 +281,9 @@ async function* streamResponse(plan, ctx, schema, report) {
                 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.
         const cursors = [];

package/dist/postgres-storage.js

@@ -107,6 +107,7 @@ function serializePushResult(result) {
                     code: record.code,
                     message: record.message,
                     retryable: record.retryable,
+                    ...(record.details !== undefined ? { details: record.details } : {}),
                 };
             }
             return { opIndex: record.opIndex, status: record.status };
@@ -133,6 +134,7 @@ function deserializePushResult(value) {
                 code: record.code ?? '',
                 message: record.message ?? '',
                 retryable: record.retryable ?? false,
+                ...(record.details !== undefined ? { details: record.details } : {}),
             };
         }
         return { opIndex: record.opIndex, status: 'applied' };

package/dist/push.js

@@ -36,10 +36,17 @@ function blobIdsInRow(table, values) {
     }
     return ids;
 }
-function errorRecord(opIndex, code, message, retryable = false) {
+function errorRecord(opIndex, code, message, retryable = false, details) {
     return {
         kind: 'terminate',
-        record: { opIndex, status: 'error', code, message, retryable },
+        record: {
+            opIndex,
+            status: 'error',
+            code,
+            message,
+            retryable,
+            ...(details !== undefined ? { details } : {}),
+        },
     };
 }
 function conflictRecord(opIndex, serverVersion, serverRow) {
@@ -83,7 +90,7 @@ async function runValidator(validators, table, op, rowId, values, storedValues,
     }
     catch (error) {
         if (error instanceof ValidationRejection) {
-            return errorRecord(opIndex, error.code, error.message);
+            return errorRecord(opIndex, error.code, error.message, false, error.details);
         }
         // §6.7: a non-ValidationRejection throw is still a rejection, mapped to
         // the generic server-side constraint code (§10.2) — the validator's

package/dist/realtime.d.ts

@@ -20,10 +20,13 @@ import type { ServerSchema } from './schema.js';
 import type { SegmentStore } from './segment-store.js';
 import type { SegmentUrlConfig } from './signed-url.js';
 import type { ServerStorage, StoredCommit } from './storage.js';
+import type { ValidatorRegistry } from './validate.js';
 export interface RealtimeHubConfig {
     readonly schema: ServerSchema;
     readonly storage: ServerStorage;
     readonly resolveScopes: ResolveScopes;
+    /** §6.7 validators used by sync rounds carried over this socket. */
+    readonly validators?: ValidatorRegistry;
     readonly clock?: () => number;
     /** Deltas larger than this become `delta-too-large` wake-ups (§8.2). */
     readonly maxDeltaBytes?: number;

package/dist/realtime.js

@@ -716,6 +716,9 @@ export class RealtimeHub {
             storage: this.#config.storage,
             segments,
             resolveScopes: this.#config.resolveScopes,
+            ...(this.#config.validators !== undefined
+                ? { validators: this.#config.validators }
+                : {}),
             ...(this.#config.clock !== undefined
                 ? { clock: this.#config.clock }
                 : {}),

package/dist/sqlite-dialect.js

@@ -111,6 +111,7 @@ export function serializePushResult(result) {
                     code: record.code,
                     message: record.message,
                     retryable: record.retryable,
+                    ...(record.details !== undefined ? { details: record.details } : {}),
                 };
             }
             return { opIndex: record.opIndex, status: record.status };
@@ -137,6 +138,7 @@ export function deserializePushResult(text) {
                 code: record.code ?? '',
                 message: record.message ?? '',
                 retryable: record.retryable ?? false,
+                ...(record.details !== undefined ? { details: record.details } : {}),
             };
         }
         return { opIndex: record.opIndex, status: 'applied' };

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 } 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)
@@ -77,7 +77,12 @@ 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);
 }
 /** 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,8 @@ export class ValidationRejection extends Error {
             }
         }
         this.code = code;
+        this.details =
+            details === undefined ? undefined : normalizeRejectionDetails(details);
     }
 }
 /** Build the column-keyed row object a validator inspects (§6.7). */

package/package.json

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

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' };

package/src/push.ts

@@ -25,6 +25,7 @@ import {
   type PushOperationResult,
   type PushResultFrame,
   parseBlobRef,
+  type RejectionDetails,
   type RowValue,
 } from '@syncular/core';
 import type { BlobStore } from './blob-store';
@@ -70,10 +71,18 @@ function errorRecord(
   code: string,
   message: string,
   retryable = false,
+  details?: RejectionDetails,
 ): OperationOutcome {
   return {
     kind: 'terminate',
-    record: { opIndex, status: 'error', code, message, retryable },
+    record: {
+      opIndex,
+      status: 'error',
+      code,
+      message,
+      retryable,
+      ...(details !== undefined ? { details } : {}),
+    },
   };
 }
 
@@ -141,7 +150,13 @@ async function runValidator(
     );
   } catch (error) {
     if (error instanceof ValidationRejection) {
-      return errorRecord(opIndex, error.code, error.message);
+      return errorRecord(
+        opIndex,
+        error.code,
+        error.message,
+        false,
+        error.details,
+      );
     }
     // §6.7: a non-ValidationRejection throw is still a rejection, mapped to
     // the generic server-side constraint code (§10.2) — the validator's

package/src/realtime.ts

@@ -50,11 +50,14 @@ import {
 import type { SegmentStore } from './segment-store';
 import type { SegmentUrlConfig } from './signed-url';
 import type { ServerStorage, StoredCommit } from './storage';
+import type { ValidatorRegistry } from './validate';
 
 export interface RealtimeHubConfig {
   readonly schema: ServerSchema;
   readonly storage: ServerStorage;
   readonly resolveScopes: ResolveScopes;
+  /** §6.7 validators used by sync rounds carried over this socket. */
+  readonly validators?: ValidatorRegistry;
   readonly clock?: () => number;
   /** Deltas larger than this become `delta-too-large` wake-ups (§8.2). */
   readonly maxDeltaBytes?: number;
@@ -926,6 +929,9 @@ export class RealtimeHub {
       storage: this.#config.storage,
       segments,
       resolveScopes: this.#config.resolveScopes,
+      ...(this.#config.validators !== undefined
+        ? { validators: this.#config.validators }
+        : {}),
       ...(this.#config.clock !== undefined
         ? { clock: this.#config.clock }
         : {}),

package/src/sqlite-dialect.ts

@@ -126,6 +126,7 @@ interface SerializedResult {
   serverVersion?: number;
   serverRow?: string;
   retryable?: boolean;
+  details?: import('@syncular/core').RejectionDetails;
 }
 
 /** Serialize a push result to the JSON `TEXT` stored in `sync_push_results`. */
@@ -151,6 +152,7 @@ export function serializePushResult(result: StoredPushResult): string {
           code: record.code,
           message: record.message,
           retryable: record.retryable,
+          ...(record.details !== undefined ? { details: record.details } : {}),
         };
       }
       return { opIndex: record.opIndex, status: record.status };
@@ -182,6 +184,7 @@ export function deserializePushResult(text: string): StoredPushResult {
         code: record.code ?? '',
         message: record.message ?? '',
         retryable: record.retryable ?? false,
+        ...(record.details !== undefined ? { details: record.details } : {}),
       };
     }
     return { opIndex: record.opIndex, status: 'applied' };

package/src/validate.ts

@@ -13,7 +13,12 @@
  * 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 {
+  normalizeRejectionDetails,
+  type RejectionDetails,
+  type RowColumn,
+  type RowValue,
+} from '@syncular/core';
 
 /**
  * §6.7 reserved code prefixes. A host validator code MUST NOT start with
@@ -93,8 +98,13 @@ export type ValidatorRegistry = Readonly<Record<string, Validator>>;
 export class ValidationRejection extends Error {
   override readonly name = 'ValidationRejection';
   readonly code: 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) {
+  constructor(code: string, message?: string, details?: RejectionDetails) {
     super(message ?? code);
     if (code.length === 0) {
       throw new Error('ValidationRejection code must be non-empty (§6.7)');
@@ -107,6 +117,8 @@ export class ValidationRejection extends Error {
       }
     }
     this.code = code;
+    this.details =
+      details === undefined ? undefined : normalizeRejectionDetails(details);
   }
 }