@syncular/server 0.15.21 → 0.15.23

package/dist/seed.js

@@ -11,7 +11,36 @@
  */
 import { decodeMessage, encodeMessage, encodeRow, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
 import { SyncError } from './errors.js';
+import { composeEvents } from './events-ring.js';
 import { handleSyncRequest } from './handler.js';
+/** Structured terminal failure from the real push path used by a seed. */
+export class SeedMutationError extends Error {
+    name = 'SeedMutationError';
+    clientId;
+    clientCommitId;
+    opIndex;
+    /** Exact protocol or host-validator rejection code. */
+    code;
+    replayed;
+    retryable;
+    recordedAtMs;
+    cacheIdentity;
+    constructor(options) {
+        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. */
 function snakeToCamel(name) {
@@ -35,8 +64,8 @@ function snakeToCamel(name) {
 }
 /**
  * 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, target, mutations) {
     const clientId = target.clientId ?? 'seed';
@@ -88,11 +117,28 @@ export async function seedMutations(config, target, mutations) {
             accept: 0b0011,
         },
     ];
+    let terminalEvent;
+    const capture = {
+        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.
     const message = decodeMessage(response);
     const result = message.frames.find((frame) => frame.type === 'PUSH_RESULT' && frame.clientCommitId === clientCommitId);
@@ -101,9 +147,27 @@ export async function seedMutations(config, target, mutations) {
     }
     if (result.status === 'rejected') {
         const failed = result.results.find((r) => r.status !== 'applied');
-        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}`);
+        const code = failed?.code ?? 'sync.invalid_request';
+        const opIndex = failed?.opIndex ?? 0;
+        const retryable = failed?.status === 'error' ? failed.retryable : false;
+        const 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/dist/sqlite-dialect.js

@@ -93,6 +93,12 @@ export function serializePushResult(result) {
     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 {
@@ -146,6 +152,12 @@ export function deserializePushResult(text) {
     return {
         status: parsed.status,
         ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
+        ...(parsed.recordedAtMs !== undefined
+            ? { recordedAtMs: parsed.recordedAtMs }
+            : {}),
+        ...(parsed.cacheIdentity !== undefined
+            ? { cacheIdentity: parsed.cacheIdentity }
+            : {}),
         results,
     };
 }

package/dist/sqlite-storage.d.ts

@@ -8,7 +8,7 @@
  */
 import { Database } from 'bun:sqlite';
 import type { CompiledSchema, CompiledTable } from './schema.js';
-import type { ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
+import type { ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredRow } from './storage.js';
 export declare class SqliteServerStorage implements ServerStorage {
     #private;
     readonly db: Database;
@@ -28,6 +28,7 @@ export declare class SqliteServerStorage implements ServerStorage {
     getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
     readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
+    scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
     getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
     putClientRecord(partition: string, record: ClientRecord): Promise<void>;
     listClientCursors(partition: string): Promise<ClientCursorInfo[]>;

package/dist/sqlite-storage.js

@@ -8,10 +8,11 @@
  */
 import { Database } from 'bun:sqlite';
 import { syncError } from './errors.js';
-import { commitWindowPageSql, deleteRowSql, dropTableDdl, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.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';
 class SqliteTransaction {
     #storage;
     #partition;
@@ -34,6 +35,10 @@ class SqliteTransaction {
         this.#assertOpen();
         return this.#storage.scanRows(this.#partition, query);
     }
+    scanRowsByIndex(query) {
+        this.#assertOpen();
+        return this.#storage.scanRowsByIndex(this.#partition, query);
+    }
     async lockPartitionForCommitValidation() {
         this.#assertOpen();
         // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
@@ -339,6 +344,7 @@ export class SqliteServerStorage {
         return commits;
     }
     async scanRows(partition, query) {
+        assertScopeIndexedScan(query);
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];
         if (firstVariable === undefined)
@@ -377,6 +383,16 @@ export class SqliteServerStorage {
         }
         return rows;
     }
+    async scanRowsByIndex(partition, query) {
+        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;
+        const records = this.db
+            .query(statement.sql)
+            .all(...params);
+        return records.map(toStoredRow);
+    }
     async getClientRecord(partition, clientId) {
         const record = this.db
             .query('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? AND client_id=?')

package/dist/storage-errors.d.ts

@@ -8,6 +8,17 @@ export declare class StorageConstraintError extends Error {
     readonly opIndex: number | undefined;
     constructor(cause: unknown, opIndex?: number);
 }
+/** Stable, privacy-safe failures for trusted server storage queries. */
+export type StorageQueryErrorCode = 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit';
+/**
+ * Host-only query error. Messages never include identifiers, values, SQL,
+ * paths, or row data; callers branch on `code`, never message text.
+ */
+export declare class StorageQueryError extends Error {
+    readonly name = "StorageQueryError";
+    readonly code: StorageQueryErrorCode;
+    constructor(code: StorageQueryErrorCode);
+}
 /** SQLite primary/extended constraint result codes (`SQLITE_CONSTRAINT*`). */
 export declare function isSqliteConstraintError(error: unknown): boolean;
 /** PostgreSQL SQLSTATE class 23: integrity constraint violation. */

package/dist/storage-errors.js

@@ -11,6 +11,25 @@ export class StorageConstraintError extends Error {
         this.opIndex = opIndex;
     }
 }
+const STORAGE_QUERY_MESSAGES = {
+    'sync.storage.scan_requires_scope': 'scope-indexed row scans require at least one scope variable',
+    'sync.storage.index_not_found': 'trusted row lookup requires a declared relational index',
+    'sync.storage.index_not_materialized': 'trusted row lookup requires a materialized relational table',
+    'sync.storage.index_value_count_mismatch': 'trusted row lookup requires one exact value per index column',
+    'sync.storage.invalid_limit': 'trusted row lookup limit must be an integer from 1 through 1,000',
+};
+/**
+ * Host-only query error. Messages never include identifiers, values, SQL,
+ * paths, or row data; callers branch on `code`, never message text.
+ */
+export class StorageQueryError extends Error {
+    name = 'StorageQueryError';
+    code;
+    constructor(code) {
+        super(STORAGE_QUERY_MESSAGES[code]);
+        this.code = code;
+    }
+}
 function driverError(error) {
     return typeof error === 'object' && error !== null
         ? error

package/dist/storage-query.d.ts

@@ -0,0 +1,6 @@
+import type { CompiledTable, IndexSchema } from './schema.js';
+import type { IndexRowScanQuery, RowScanQuery } from './storage.js';
+/** Fail loudly instead of making an unsupported unscoped scan look empty. */
+export declare function assertScopeIndexedScan(query: RowScanQuery): void;
+/** Validate and resolve one exact trusted-host relational index lookup. */
+export declare function resolveIndexRowScan(table: CompiledTable, query: IndexRowScanQuery): IndexSchema;

package/dist/storage-query.js

@@ -0,0 +1,30 @@
+import { StorageQueryError } from './storage-errors.js';
+/** Fail loudly instead of making an unsupported unscoped scan look empty. */
+export function assertScopeIndexedScan(query) {
+    const scopeFilter = query.scopeFilter;
+    if (scopeFilter === undefined ||
+        scopeFilter === null ||
+        Object.keys(scopeFilter).length === 0) {
+        throw new StorageQueryError('sync.storage.scan_requires_scope');
+    }
+}
+/** Validate and resolve one exact trusted-host relational index lookup. */
+export function resolveIndexRowScan(table, query) {
+    if (!Number.isInteger(query.limit) ||
+        query.limit < 1 ||
+        query.limit > 1_000) {
+        throw new StorageQueryError('sync.storage.invalid_limit');
+    }
+    if (!table.materialize) {
+        throw new StorageQueryError('sync.storage.index_not_materialized');
+    }
+    const index = table.indexes.find((candidate) => candidate.name === query.index);
+    if (index === undefined) {
+        throw new StorageQueryError('sync.storage.index_not_found');
+    }
+    if (!Array.isArray(query.values) ||
+        query.values.length !== index.columns.length) {
+        throw new StorageQueryError('sync.storage.index_value_count_mismatch');
+    }
+    return index;
+}

package/dist/storage.d.ts

@@ -16,7 +16,7 @@
  * The interface is async throughout so a Postgres implementation slots in
  * without touching the core. All methods are partition-local (§2.1).
  */
-import type { PushOperationResult, ScopeMap } from '@syncular/core';
+import type { PushOperationResult, RowValue, ScopeMap } from '@syncular/core';
 import type { CompiledSchema } from './schema.js';
 /** The current stored state of a synced row. */
 export interface StoredRow {
@@ -64,6 +64,10 @@ export interface StoredPushResult {
     readonly status: 'applied' | 'rejected';
     /** Present iff `status` is `applied`. */
     readonly commitSeq?: number;
+    /** Host clock when this terminal idempotency outcome was first recorded. */
+    readonly recordedAtMs?: number;
+    /** Privacy-safe identity used to distinguish this stored outcome from a race. */
+    readonly cacheIdentity?: string;
     readonly results: readonly PushOperationResult[];
 }
 export interface ClientSubscription {
@@ -102,6 +106,25 @@ export interface RowScanQuery {
     readonly afterRowId: string | null;
     readonly limit: number;
 }
+/**
+ * Exact server-host lookup through one declared relational index.
+ *
+ * This is deliberately NOT a Syncular scope or client query. It is available
+ * only to trusted server code that already owns a `ServerStorage` or
+ * `StorageTransaction` capability. Every declared index column must have one
+ * exact value, so adapters can keep the lookup bounded and deterministic.
+ */
+export interface IndexRowScanQuery {
+    readonly table: string;
+    /** `TableSchema.indexes[].name`; never exposed as a client subscription. */
+    readonly index: string;
+    /** Exact values in the index declaration's column order. */
+    readonly values: readonly RowValue[];
+    /** Resume after this rowId (exclusive); `null` = start of the match set. */
+    readonly afterRowId?: string | null;
+    /** Integer from 1 through 1,000. */
+    readonly limit: number;
+}
 export interface ClientCursorInfo {
     readonly clientId: string;
     readonly cursor: number;
@@ -156,6 +179,12 @@ export interface StorageTransaction {
      * semantics. A custom backend may omit it until `commitValidator` is used.
      */
     scanRows?(query: RowScanQuery): Promise<StoredRow[]>;
+    /**
+     * Optional additive capability for trusted authoritative commands. In-tree
+     * SQLite/PostgreSQL/D1 adapters implement it with transaction-local
+     * read-your-own-writes semantics. It is not reachable from SSP2 requests.
+     */
+    scanRowsByIndex?(query: IndexRowScanQuery): Promise<StoredRow[]>;
     /**
      * Serialize candidate-state validation for this partition before any row
      * read/write. Required at runtime when `commitValidator` is configured.
@@ -227,6 +256,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 trusted-host exact lookup through a declared relational index.
+     * This capability is outside client scope/subscription authorization and
+     * MUST NOT be re-exported as a client-controlled endpoint.
+     */
+    scanRowsByIndex?(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
     getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
     putClientRecord(partition: string, record: ClientRecord): Promise<void>;
     /** Cursor records feeding the §4.6 retention watermark. */

package/package.json

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

package/src/d1-storage.ts

@@ -45,6 +45,7 @@ import {
   commitWindowPageSql,
   deleteRowSql,
   dropTableDdl,
+  indexRowPageStatement,
   layoutsOf,
   migratePayload,
   parseLayouts,
@@ -84,6 +85,7 @@ import type {
   CommitMetadata,
   CommitMetadataQuery,
   CommitWindowQuery,
+  IndexRowScanQuery,
   NewCommit,
   RowScanQuery,
   ScopeActivityQuery,
@@ -95,6 +97,7 @@ import type {
   StoredRow,
 } from './storage';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors';
+import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query';
 
 // -- The subset of the D1 API this storage uses (structural typing) ---------
 // Declared locally so the package takes no `@cloudflare/workers-types`
@@ -193,6 +196,7 @@ class D1Transaction 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 [];
@@ -254,6 +258,60 @@ class D1Transaction implements StorageTransaction {
       .slice(0, query.limit);
   }
 
+  async scanRowsByIndex(query: IndexRowScanQuery): Promise<StoredRow[]> {
+    this.#assertOpen();
+    const table = this.#resolveTable(query.table);
+    const index = resolveIndexRowScan(table, query);
+    const pendingForTable = [...this.#pending.entries()].filter(([key]) =>
+      key.startsWith(`${query.table}\u0000`),
+    );
+    const persistedLimit = query.limit + pendingForTable.length;
+    const statement = indexRowPageStatement(
+      table,
+      index,
+      query.values,
+      this.#partition,
+      query.afterRowId,
+      persistedLimit,
+      'sqlite',
+    );
+    const { results: records } = await this.#db
+      .prepare(statement.sql)
+      .bind(...statement.params)
+      .all<SqliteRowRecord>();
+
+    const rows = new Map(
+      records.map((record) => {
+        const row = toStoredRow(record);
+        return [row.rowId, row] as const;
+      }),
+    );
+    const columnPositions = index.columns.map((column) => {
+      const position = table.columnIndex.get(column);
+      if (position === undefined) {
+        throw new Error('compiled relational index references unknown column');
+      }
+      return position;
+    });
+    const lowerBound = query.afterRowId ?? '';
+    for (const [key, pending] of pendingForTable) {
+      const rowId = key.slice(query.table.length + 1);
+      rows.delete(rowId);
+      if (pending.kind !== 'row' || rowId <= lowerBound) continue;
+      const values = decodeRow(table.columns, pending.row.payload);
+      const matches = columnPositions.every((position, valueIndex) =>
+        relationalValuesEqual(
+          values[position] ?? null,
+          query.values[valueIndex] ?? null,
+        ),
+      );
+      if (matches) rows.set(rowId, pending.row);
+    }
+    return [...rows.values()]
+      .sort((left, right) => left.rowId.localeCompare(right.rowId))
+      .slice(0, query.limit);
+  }
+
   async lockPartitionForCommitValidation(): Promise<void> {
     this.#assertOpen();
     if (!this.#commitValidationSerialized) {
@@ -859,6 +917,7 @@ export class D1ServerStorage 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 [];
@@ -904,6 +963,28 @@ export class D1ServerStorage 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 { results } = await this.#db
+      .prepare(statement.sql)
+      .bind(...statement.params)
+      .all<SqliteRowRecord>();
+    return results.map(toStoredRow);
+  }
+
   async getClientRecord(
     partition: string,
     clientId: string,

package/src/events.ts

@@ -63,12 +63,22 @@ export interface PushRejectedEvent extends PushEventBase {
   readonly type: 'push.rejected';
   readonly code: string;
   readonly opIndex: number;
+  /** True when the rejection was replayed from the idempotency cache. */
+  readonly replay: boolean;
+  /** Original host time for outcomes recorded by a metadata-aware server. */
+  readonly recordedAtMs?: number;
+  /** Privacy-safe identity of the stored outcome, when available. */
+  readonly cacheIdentity?: string;
 }
 
 /** A push commit terminated by a version conflict (§6.2). */
 export interface PushConflictedEvent extends PushEventBase {
   readonly type: 'push.conflicted';
   readonly opIndex: number;
+  /** True when the conflict was replayed from the idempotency cache. */
+  readonly replay: boolean;
+  readonly recordedAtMs?: number;
+  readonly cacheIdentity?: string;
 }
 
 /** One emitted segment within a pull subscription section. */

package/src/handler.ts

@@ -44,7 +44,7 @@ import {
   type SubscriptionPlan,
   subscriptionSection,
 } from './pull';
-import { processPushCommit } from './push';
+import { type ProcessedPushCommit, processPushCommitWithTrace } from './push';
 import type { CompiledSchema } from './schema';
 import { compileSchema } from './schema';
 import { computeEffective, type ResolvedScopes } from './scopes';
@@ -339,8 +339,9 @@ function emitPushEvent(
   ctx: SyncRequestContext,
   clientId: string,
   push: PushCommitFrame,
-  frame: PushResultFrame,
+  processed: ProcessedPushCommit,
 ): void {
+  const { frame } = processed;
   const base = {
     atMs: clockOf(ctx)(),
     partition: ctx.partition,
@@ -354,7 +355,7 @@ function emitPushEvent(
       type: 'push.applied',
       ...base,
       ...(frame.commitSeq !== undefined ? { commitSeq: frame.commitSeq } : {}),
-      replay: frame.status === 'cached',
+      replay: processed.replayed,
     });
     return;
   }
@@ -365,6 +366,13 @@ function emitPushEvent(
       type: 'push.conflicted',
       ...base,
       opIndex: record.opIndex,
+      replay: processed.replayed,
+      ...(processed.recordedAtMs !== undefined
+        ? { recordedAtMs: processed.recordedAtMs }
+        : {}),
+      ...(processed.cacheIdentity !== undefined
+        ? { cacheIdentity: processed.cacheIdentity }
+        : {}),
     });
     return;
   }
@@ -376,6 +384,13 @@ function emitPushEvent(
         ? record.code
         : 'sync.invalid_request',
     opIndex: record?.opIndex ?? 0,
+    replay: processed.replayed,
+    ...(processed.recordedAtMs !== undefined
+      ? { recordedAtMs: processed.recordedAtMs }
+      : {}),
+    ...(processed.cacheIdentity !== undefined
+      ? { cacheIdentity: processed.cacheIdentity }
+      : {}),
   });
 }
 
@@ -423,15 +438,16 @@ async function* streamResponse(
   try {
     // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
     for (const push of plan.pushes) {
-      const frame = await processPushCommit(
+      const processed = await processPushCommitWithTrace(
         ctx,
         schema,
         plan.resolved,
         plan.header.clientId,
         push,
       );
+      const { frame } = processed;
       if (events !== undefined) {
-        emitPushEvent(events, ctx, plan.header.clientId, push, frame);
+        emitPushEvent(events, ctx, plan.header.clientId, push, processed);
       }
       yield encodeResponseFrame(frame);
       const details = pushResultDetailsFrame(frame);

package/src/index.ts

@@ -51,4 +51,8 @@ export * from './sqlite-lease-store';
 export * from './sqlite-segment-store';
 export * from './sqlite-storage';
 export * from './storage';
+export {
+  StorageQueryError,
+  type StorageQueryErrorCode,
+} from './storage-errors';
 export * from './validate';