@syncular/server 0.15.21 → 0.15.23

package/src/postgres-storage.ts

@@ -47,6 +47,7 @@ import {
   commitWindowPageSql,
   deleteRowSql,
   dropTableDdl,
+  indexRowPageStatement,
   layoutsOf,
   migratePayload,
   parseLayouts,
@@ -73,6 +74,7 @@ import type {
   CommitMetadata,
   CommitMetadataQuery,
   CommitWindowQuery,
+  IndexRowScanQuery,
   NewCommit,
   RowScanQuery,
   ScopeActivityQuery,
@@ -88,6 +90,7 @@ import {
   isPostgresConstraintError,
   StorageConstraintError,
 } from './storage-errors';
+import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query';
 
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
@@ -190,6 +193,12 @@ function serializePushResult(result: StoredPushResult): unknown {
   return {
     status: result.status,
     ...(result.commitSeq !== undefined ? { commitSeq: result.commitSeq } : {}),
+    ...(result.recordedAtMs !== undefined
+      ? { recordedAtMs: result.recordedAtMs }
+      : {}),
+    ...(result.cacheIdentity !== undefined
+      ? { cacheIdentity: result.cacheIdentity }
+      : {}),
     results: result.results.map((record) => {
       if (record.status === 'conflict') {
         return {
@@ -220,6 +229,8 @@ function deserializePushResult(value: unknown): StoredPushResult {
   const parsed = value as {
     status: 'applied' | 'rejected';
     commitSeq?: number;
+    recordedAtMs?: number;
+    cacheIdentity?: string;
     results: SerializedResult[];
   };
   const results: PushOperationResult[] = parsed.results.map((record) => {
@@ -248,6 +259,12 @@ function deserializePushResult(value: unknown): StoredPushResult {
   return {
     status: parsed.status,
     ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
+    ...(parsed.recordedAtMs !== undefined
+      ? { recordedAtMs: parsed.recordedAtMs }
+      : {}),
+    ...(parsed.cacheIdentity !== undefined
+      ? { cacheIdentity: parsed.cacheIdentity }
+      : {}),
     results,
   };
 }
@@ -374,6 +391,26 @@ async function getRowOn(
   return record === undefined ? undefined : toStoredRow(record);
 }
 
+async function scanRowsByIndexOn(
+  q: PgQueryable,
+  compiled: CompiledTable,
+  partition: string,
+  query: IndexRowScanQuery,
+): Promise<StoredRow[]> {
+  const index = resolveIndexRowScan(compiled, query);
+  const statement = indexRowPageStatement(
+    compiled,
+    index,
+    query.values,
+    partition,
+    query.afterRowId,
+    query.limit,
+    'postgres',
+  );
+  const { rows } = await q.query<RowRecord>(statement.sql, statement.params);
+  return rows.map(toStoredRow);
+}
+
 async function writeRowOn(
   q: PgQueryable,
   compiled: CompiledTable,
@@ -437,6 +474,7 @@ class PostgresTransaction implements StorageTransaction {
 
   async scanRows(query: RowScanQuery): Promise<StoredRow[]> {
     this.#assertOpen();
+    assertScopeIndexedScan(query);
     const variables = Object.keys(query.scopeFilter).sort();
     const firstVariable = variables[0];
     if (firstVariable === undefined) return [];
@@ -473,6 +511,16 @@ class PostgresTransaction implements StorageTransaction {
     return rows;
   }
 
+  scanRowsByIndex(query: IndexRowScanQuery): Promise<StoredRow[]> {
+    this.#assertOpen();
+    return scanRowsByIndexOn(
+      this.#client,
+      this.#resolveTable(query.table),
+      this.#partition,
+      query,
+    );
+  }
+
   async lockPartitionForCommitValidation(): Promise<void> {
     this.#assertOpen();
     await this.#client.query(
@@ -1012,6 +1060,7 @@ export class PostgresServerStorage implements ServerStorage {
   }
 
   async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
+    assertScopeIndexedScan(query);
     const variables = Object.keys(query.scopeFilter).sort();
     const firstVariable = variables[0];
     if (firstVariable === undefined) return [];
@@ -1054,6 +1103,18 @@ export class PostgresServerStorage implements ServerStorage {
     return rows;
   }
 
+  scanRowsByIndex(
+    partition: string,
+    query: IndexRowScanQuery,
+  ): Promise<StoredRow[]> {
+    return scanRowsByIndexOn(
+      this.#exec,
+      this.table(query.table),
+      partition,
+      query,
+    );
+  }
+
   async getClientRecord(
     partition: string,
     clientId: string,

package/src/push.ts

@@ -750,6 +750,42 @@ function resultFrame(
   };
 }
 
+export interface ProcessedPushCommit {
+  readonly frame: PushResultFrame;
+  /** True when this request observed an already-recorded idempotency outcome. */
+  readonly replayed: boolean;
+  readonly recordedAtMs?: number;
+  readonly cacheIdentity?: string;
+}
+
+function processedPushCommit(
+  clientCommitId: string,
+  stored: StoredPushResult,
+  replayed: boolean,
+): ProcessedPushCommit {
+  return {
+    frame: resultFrame(clientCommitId, stored, replayed),
+    replayed,
+    ...(stored.recordedAtMs !== undefined
+      ? { recordedAtMs: stored.recordedAtMs }
+      : {}),
+    ...(stored.cacheIdentity !== undefined
+      ? { cacheIdentity: stored.cacheIdentity }
+      : {}),
+  };
+}
+
+function newStoredPushResult(
+  recordedAtMs: number,
+  result: Omit<StoredPushResult, 'recordedAtMs' | 'cacheIdentity'>,
+): StoredPushResult {
+  return {
+    ...result,
+    recordedAtMs,
+    cacheIdentity: crypto.randomUUID(),
+  };
+}
+
 function idempotencyCacheMissFrame(
   clientCommitId: string,
   error: SyncError,
@@ -776,7 +812,7 @@ async function persistRejectedPushResult(
   clientId: string,
   clientCommitId: string,
   stored: StoredPushResult,
-): Promise<StoredPushResult> {
+): Promise<{ readonly stored: StoredPushResult; readonly replayed: boolean }> {
   const rejectionTx = await storage.begin(partition);
   try {
     await rejectionTx.putPushResult(clientId, clientCommitId, stored);
@@ -793,7 +829,10 @@ async function persistRejectedPushResult(
   if (canonical === undefined) {
     throw new Error('push rejection finalization did not persist an outcome');
   }
-  return canonical;
+  return {
+    stored: canonical,
+    replayed: canonical.cacheIdentity !== stored.cacheIdentity,
+  };
 }
 
 export interface AppliedCommitEvent {
@@ -811,6 +850,23 @@ export async function processPushCommit(
   clientId: string,
   frame: PushCommitFrame,
 ): Promise<PushResultFrame> {
+  return (
+    await processPushCommitWithTrace(ctx, schema, resolved, clientId, frame)
+  ).frame;
+}
+
+/**
+ * Host-observable variant of `processPushCommit`. The SSP2 wire frame keeps
+ * rejected replays as `status: rejected`; this companion result preserves the
+ * cache provenance needed by structured events and server helpers.
+ */
+export async function processPushCommitWithTrace(
+  ctx: SyncRequestContext,
+  schema: CompiledSchema,
+  resolved: ResolvedScopes,
+  clientId: string,
+  frame: PushCommitFrame,
+): Promise<ProcessedPushCommit> {
   const { storage, partition } = ctx;
   let persisted: StoredPushResult | undefined;
   try {
@@ -826,12 +882,15 @@ export async function processPushCommit(
     ) {
       // §6.3: answer the retryable cache-miss for this commit rather than
       // re-applying. Not persisted — a retry may find a readable record.
-      return idempotencyCacheMissFrame(frame.clientCommitId, error);
+      return {
+        frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+        replayed: false,
+      };
     }
     throw error;
   }
   if (persisted !== undefined) {
-    return resultFrame(frame.clientCommitId, persisted, true);
+    return processedPushCommit(frame.clientCommitId, persisted, true);
   }
 
   const createdAtMs = clockOf(ctx)();
@@ -863,7 +922,11 @@ export async function processPushCommit(
         );
         if (serializedPersisted !== undefined) {
           await tx.rollback();
-          return resultFrame(frame.clientCommitId, serializedPersisted, true);
+          return processedPushCommit(
+            frame.clientCommitId,
+            serializedPersisted,
+            true,
+          );
         }
       } catch (error) {
         if (
@@ -871,7 +934,10 @@ export async function processPushCommit(
           error.code === 'sync.idempotency_cache_miss'
         ) {
           await tx.rollback();
-          return idempotencyCacheMissFrame(frame.clientCommitId, error);
+          return {
+            frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+            replayed: false,
+          };
         }
         throw error;
       }
@@ -923,10 +989,10 @@ export async function processPushCommit(
     if (terminated !== undefined) {
       // §6.3 rejected: only the terminating operation's record; §6.4:
       // every write of the commit rolls back.
-      const stored: StoredPushResult = {
+      const stored = newStoredPushResult(createdAtMs, {
         status: 'rejected',
         results: [terminated],
-      };
+      });
       if (commitValidator !== undefined) {
         // Discard candidate rows and persist the rejection while retaining the
         // same partition lock. This closes the duplicate-request race between
@@ -946,13 +1012,13 @@ export async function processPushCommit(
           frame.clientCommitId,
           stored,
         );
-        return resultFrame(
+        return processedPushCommit(
           frame.clientCommitId,
-          canonical,
-          canonical !== stored,
+          canonical.stored,
+          canonical.replayed,
         );
       }
-      return resultFrame(frame.clientCommitId, stored, false);
+      return processedPushCommit(frame.clientCommitId, stored, false);
     }
 
     const commitSeq = await tx.appendCommit({
@@ -962,7 +1028,11 @@ export async function processPushCommit(
       createdAtMs,
       changes,
     });
-    const stored: StoredPushResult = { status: 'applied', commitSeq, results };
+    const stored = newStoredPushResult(createdAtMs, {
+      status: 'applied',
+      commitSeq,
+      results,
+    });
     await tx.putPushResult(clientId, frame.clientCommitId, stored);
     await tx.commit();
     if (ctx.realtime !== undefined && changes.length > 0) {
@@ -973,11 +1043,11 @@ export async function processPushCommit(
         changes,
       });
     }
-    return resultFrame(frame.clientCommitId, stored, false);
+    return processedPushCommit(frame.clientCommitId, stored, false);
   } catch (error) {
     await tx.rollback();
     if (error instanceof StorageConstraintError) {
-      const stored: StoredPushResult = {
+      const stored = newStoredPushResult(createdAtMs, {
         status: 'rejected',
         results: [
           {
@@ -988,7 +1058,7 @@ export async function processPushCommit(
             retryable: false,
           },
         ],
-      };
+      });
       const canonical = await persistRejectedPushResult(
         storage,
         partition,
@@ -996,7 +1066,11 @@ export async function processPushCommit(
         frame.clientCommitId,
         stored,
       );
-      return resultFrame(frame.clientCommitId, canonical, canonical !== stored);
+      return processedPushCommit(
+        frame.clientCommitId,
+        canonical.stored,
+        canonical.replayed,
+      );
     }
     throw error;
   }

package/src/relational-rows.ts

@@ -49,7 +49,7 @@ import {
   type RowColumn,
   type RowValue,
 } from '@syncular/core';
-import type { CompiledSchema, CompiledTable } from './schema';
+import type { CompiledSchema, CompiledTable, IndexSchema } from './schema';
 import type { StoredRow } from './storage';
 
 export type RelationalDialect = 'sqlite' | 'postgres';
@@ -287,6 +287,50 @@ export function selectRowSql(
   return `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${p[0]} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${p[1]}`;
 }
 
+export interface IndexRowPageStatement {
+  readonly sql: string;
+  readonly params: readonly unknown[];
+}
+
+/**
+ * Bounded exact lookup through one declared relational index. Unlike
+ * `scanRowPageSql`, this is a trusted server-host query: it never reads or
+ * creates Syncular scope-index entries and is not reachable from SSP2.
+ */
+export function indexRowPageStatement(
+  table: CompiledTable,
+  index: IndexSchema,
+  values: readonly RowValue[],
+  partition: string,
+  afterRowId: string | null | undefined,
+  limit: number,
+  dialect: RelationalDialect,
+): IndexRowPageStatement {
+  const params: unknown[] = [partition];
+  const placeholder = (): string =>
+    dialect === 'sqlite' ? '?' : `$${params.length}`;
+  const predicates = index.columns.map((columnName, valueIndex) => {
+    const columnPosition = table.columnIndex.get(columnName);
+    const column =
+      columnPosition === undefined ? undefined : table.columns[columnPosition];
+    if (column === undefined) {
+      throw new Error('compiled relational index references unknown column');
+    }
+    const value = values[valueIndex] ?? null;
+    if (value === null) return `${quoteIdent(columnName)} IS NULL`;
+    params.push(toSqlValue(column, value, dialect));
+    return `${quoteIdent(columnName)}=${placeholder()}`;
+  });
+  params.push(afterRowId ?? '');
+  const after = placeholder();
+  params.push(limit);
+  const pageLimit = placeholder();
+  return {
+    sql: `SELECT ${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, ${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, ${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, ${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${dialect === 'sqlite' ? '?' : '$1'} AND ${predicates.join(' AND ')} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}>${after} ORDER BY ${quoteIdent(SYNC_ROW_ID_COLUMN)} LIMIT ${pageLimit}`,
+    params,
+  };
+}
+
 /**
  * One-round-trip page scan for `scanRows`: candidates from the inverted
  * scope index (ordered + LIMITed at the covering `sync_row_scopes` PK —

package/src/schema.ts

@@ -180,6 +180,11 @@ export function compileSchema(schema: ServerSchema): CompiledSchema {
         );
       }
       indexNames.add(index.name);
+      if (index.columns.length === 0) {
+        throw new Error(
+          `table ${table.name}: index ${JSON.stringify(index.name)} must name at least one column`,
+        );
+      }
       for (const column of index.columns) {
         if (!columnIndex.has(column)) {
           throw new Error(

package/src/seed.ts

@@ -21,6 +21,8 @@ import {
 } from '@syncular/core';
 import type { SyncServerConfig } from './context';
 import { SyncError } from './errors';
+import type { SyncularServerEvent, SyncularServerEvents } from './events';
+import { composeEvents } from './events-ring';
 import { handleSyncRequest } from './handler';
 
 /** One app-shaped seed mutation — the same vocabulary as client mutations. */
@@ -54,6 +56,48 @@ export interface SeedTarget {
   readonly commitId?: string;
 }
 
+export interface SeedMutationErrorOptions {
+  readonly clientId: string;
+  readonly clientCommitId: string;
+  readonly opIndex: number;
+  readonly code: string;
+  readonly replayed: boolean;
+  readonly retryable: boolean;
+  readonly message: string;
+  readonly recordedAtMs?: number;
+  readonly cacheIdentity?: string;
+}
+
+/** Structured terminal failure from the real push path used by a seed. */
+export class SeedMutationError extends Error {
+  override readonly name = 'SeedMutationError';
+  readonly clientId: string;
+  readonly clientCommitId: string;
+  readonly opIndex: number;
+  /** Exact protocol or host-validator rejection code. */
+  readonly code: string;
+  readonly replayed: boolean;
+  readonly retryable: boolean;
+  readonly recordedAtMs?: number;
+  readonly cacheIdentity?: string;
+
+  constructor(options: SeedMutationErrorOptions) {
+    super(options.message);
+    this.clientId = options.clientId;
+    this.clientCommitId = options.clientCommitId;
+    this.opIndex = options.opIndex;
+    this.code = options.code;
+    this.replayed = options.replayed;
+    this.retryable = options.retryable;
+    if (options.recordedAtMs !== undefined) {
+      this.recordedAtMs = options.recordedAtMs;
+    }
+    if (options.cacheIdentity !== undefined) {
+      this.cacheIdentity = options.cacheIdentity;
+    }
+  }
+}
+
 const MAPPABLE_RE = /^_*[A-Za-z][A-Za-z0-9_]*$/;
 
 /** Pinned §12 schema alias used by generated row types and every client host. */
@@ -79,8 +123,8 @@ function snakeToCamel(name: string): string {
 
 /**
  * Seed `mutations` into a partition through the real push path. Throws a
- * `SyncError` when the push is rejected or any operation fails, so a broken
- * seed fails loud at boot instead of silently serving an empty database.
+ * `SeedMutationError` when the push is rejected and `SyncError` for malformed
+ * helper input, so a broken seed fails loud instead of serving an empty store.
  */
 export async function seedMutations(
   config: SyncServerConfig,
@@ -154,13 +198,37 @@ export async function seedMutations(
       accept: 0b0011,
     },
   ];
+  type SeedTerminalEvent = Extract<
+    SyncularServerEvent,
+    { type: 'push.rejected' | 'push.conflicted' }
+  >;
+  let terminalEvent: SeedTerminalEvent | undefined;
+  const capture: SyncularServerEvents = {
+    emit(event) {
+      if (
+        (event.type === 'push.rejected' || event.type === 'push.conflicted') &&
+        event.clientId === clientId &&
+        event.clientCommitId === clientCommitId
+      ) {
+        terminalEvent = event;
+      }
+    },
+  };
   const response = await handleSyncRequest(
     encodeMessage({
       wireVersion: PROTOCOL_WIRE_VERSION,
       msgKind: 'request',
       frames,
     }),
-    { ...config, partition: target.partition, actorId: target.actorId },
+    {
+      ...config,
+      partition: target.partition,
+      actorId: target.actorId,
+      events:
+        config.events === undefined
+          ? capture
+          : composeEvents(config.events, capture),
+    },
   );
 
   // Fail loud: surface the first rejected/failed operation.
@@ -177,13 +245,30 @@ export async function seedMutations(
   }
   if (result.status === 'rejected') {
     const failed = result.results.find((r) => r.status !== 'applied');
+    const code = failed?.code ?? 'sync.invalid_request';
+    const opIndex = failed?.opIndex ?? 0;
+    const retryable = failed?.status === 'error' ? failed.retryable : false;
     const detail =
-      failed !== undefined && 'code' in failed
-        ? ` (op ${failed.opIndex}: ${failed.code} — ${failed.message})`
-        : '';
-    throw new SyncError(
-      'sync.invalid_request',
-      `seedMutations: the seed commit was rejected${detail}`,
-    );
+      failed === undefined
+        ? ''
+        : ` (op ${opIndex}: ${code} — ${failed.message})`;
+    const replayed = terminalEvent?.replay ?? false;
+    throw new SeedMutationError({
+      clientId,
+      clientCommitId,
+      opIndex,
+      code,
+      replayed,
+      retryable,
+      message: `seedMutations: the seed commit was rejected${
+        replayed ? ' (cached replay)' : ''
+      }${detail}`,
+      ...(terminalEvent?.recordedAtMs !== undefined
+        ? { recordedAtMs: terminalEvent.recordedAtMs }
+        : {}),
+      ...(terminalEvent?.cacheIdentity !== undefined
+        ? { cacheIdentity: terminalEvent.cacheIdentity }
+        : {}),
+    });
   }
 }

package/src/sqlite-dialect.ts

@@ -134,6 +134,12 @@ export function serializePushResult(result: StoredPushResult): string {
   return JSON.stringify({
     status: result.status,
     ...(result.commitSeq !== undefined ? { commitSeq: result.commitSeq } : {}),
+    ...(result.recordedAtMs !== undefined
+      ? { recordedAtMs: result.recordedAtMs }
+      : {}),
+    ...(result.cacheIdentity !== undefined
+      ? { cacheIdentity: result.cacheIdentity }
+      : {}),
     results: result.results.map((record) => {
       if (record.status === 'conflict') {
         return {
@@ -164,6 +170,8 @@ export function deserializePushResult(text: string): StoredPushResult {
   const parsed = JSON.parse(text) as {
     status: 'applied' | 'rejected';
     commitSeq?: number;
+    recordedAtMs?: number;
+    cacheIdentity?: string;
     results: SerializedResult[];
   };
   const results: PushOperationResult[] = parsed.results.map((record) => {
@@ -192,6 +200,12 @@ export function deserializePushResult(text: string): StoredPushResult {
   return {
     status: parsed.status,
     ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
+    ...(parsed.recordedAtMs !== undefined
+      ? { recordedAtMs: parsed.recordedAtMs }
+      : {}),
+    ...(parsed.cacheIdentity !== undefined
+      ? { cacheIdentity: parsed.cacheIdentity }
+      : {}),
     results,
   };
 }

package/src/sqlite-storage.ts

@@ -12,6 +12,7 @@ import {
   commitWindowPageSql,
   deleteRowSql,
   dropTableDdl,
+  indexRowPageStatement,
   layoutsOf,
   migratePayload,
   parseLayouts,
@@ -47,6 +48,7 @@ import type {
   CommitMetadata,
   CommitMetadataQuery,
   CommitWindowQuery,
+  IndexRowScanQuery,
   NewCommit,
   RowScanQuery,
   ScopeActivityQuery,
@@ -61,6 +63,7 @@ import {
   isSqliteConstraintError,
   StorageConstraintError,
 } from './storage-errors';
+import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query';
 
 class SqliteTransaction implements StorageTransaction {
   #storage: SqliteServerStorage;
@@ -88,6 +91,11 @@ class SqliteTransaction implements StorageTransaction {
     return this.#storage.scanRows(this.#partition, query);
   }
 
+  scanRowsByIndex(query: IndexRowScanQuery): Promise<StoredRow[]> {
+    this.#assertOpen();
+    return this.#storage.scanRowsByIndex(this.#partition, query);
+  }
+
   async lockPartitionForCommitValidation(): Promise<void> {
     this.#assertOpen();
     // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
@@ -564,6 +572,7 @@ export class SqliteServerStorage implements ServerStorage {
   }
 
   async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
+    assertScopeIndexedScan(query);
     const variables = Object.keys(query.scopeFilter).sort();
     const firstVariable = variables[0];
     if (firstVariable === undefined) return [];
@@ -611,6 +620,35 @@ export class SqliteServerStorage implements ServerStorage {
     return rows;
   }
 
+  async scanRowsByIndex(
+    partition: string,
+    query: IndexRowScanQuery,
+  ): Promise<StoredRow[]> {
+    const table = this.table(query.table);
+    const index = resolveIndexRowScan(table, query);
+    const statement = indexRowPageStatement(
+      table,
+      index,
+      query.values,
+      partition,
+      query.afterRowId,
+      query.limit,
+      'sqlite',
+    );
+    const params = statement.params as readonly (
+      | string
+      | number
+      | Uint8Array
+      | null
+    )[];
+    const records = this.db
+      .query<SqliteRowRecord, (string | number | Uint8Array | null)[]>(
+        statement.sql,
+      )
+      .all(...params);
+    return records.map(toStoredRow);
+  }
+
   async getClientRecord(
     partition: string,
     clientId: string,