@syncular/server 0.15.22 → 0.15.23

package/README.md

@@ -173,6 +173,21 @@ Whole-commit validation checks a client-proposed commit; it does not grant
 authority. Privileged operations such as connecting facilities still belong in
 explicit server-authoritative commands.
 
+## Seed idempotency and safe revisioning
+
+`seedMutations` uses the real push path and a stable `clientId`/`commitId`.
+Both applied and rejected outcomes are terminal for that key. A rejected call
+throws `SeedMutationError`, whose structured `code`, `opIndex`, `replayed`,
+`recordedAtMs`, and `cacheIdentity` fields distinguish a fresh policy failure
+from replay of an older cached rejection.
+
+After correcting a development seed definition, advance an explicit seed
+revision (`catalog-v1` to `catalog-v2`) and rerun it; do not delete the database
+or unrelated rows. This does not apply to application commands. After an
+unknown command outcome, reuse the original idempotency key because changing it
+can execute the operation twice. The full inspection and recovery recipe is in
+the public [server guide](https://syncular.dev/guide-server/#seeding-data).
+
 The task-oriented [concurrency and conflict-correction guide](https://syncular.dev/guide-concurrency-correction/)
 shows version projection, aggregate rollback, corrected replacement commits,
 explicit acknowledgement, and restart-safe recovery UI together.

package/dist/events.d.ts

@@ -59,11 +59,21 @@ 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. */
 export interface PullSegmentSummary {

package/dist/handler.js

@@ -15,7 +15,7 @@ import { SyncError, syncError } from './errors.js';
 import { emitEvent, } from './events.js';
 import { END_FRAME_BYTES, encodeResponseFrame, RESPONSE_ENVELOPE_HEADER, } from './frame-bytes.js';
 import { ACCEPT_EXTERNAL_ROWS, ACCEPT_INLINE_ROWS, clampPullLimits, subscriptionSection, } from './pull.js';
-import { processPushCommit } from './push.js';
+import { processPushCommitWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
 import { computeEffective } from './scopes.js';
 function validateResolvedKeys(allowed, schema) {
@@ -199,7 +199,8 @@ function pushResultDetailsFrame(frame) {
             entries,
         };
 }
-function emitPushEvent(events, ctx, clientId, push, frame) {
+function emitPushEvent(events, ctx, clientId, push, processed) {
+    const { frame } = processed;
     const base = {
         atMs: clockOf(ctx)(),
         partition: ctx.partition,
@@ -213,7 +214,7 @@ function emitPushEvent(events, ctx, clientId, push, frame) {
             type: 'push.applied',
             ...base,
             ...(frame.commitSeq !== undefined ? { commitSeq: frame.commitSeq } : {}),
-            replay: frame.status === 'cached',
+            replay: processed.replayed,
         });
         return;
     }
@@ -224,6 +225,13 @@ function emitPushEvent(events, ctx, clientId, push, frame) {
             type: 'push.conflicted',
             ...base,
             opIndex: record.opIndex,
+            replay: processed.replayed,
+            ...(processed.recordedAtMs !== undefined
+                ? { recordedAtMs: processed.recordedAtMs }
+                : {}),
+            ...(processed.cacheIdentity !== undefined
+                ? { cacheIdentity: processed.cacheIdentity }
+                : {}),
         });
         return;
     }
@@ -234,6 +242,13 @@ function emitPushEvent(events, ctx, clientId, push, frame) {
             ? record.code
             : 'sync.invalid_request',
         opIndex: record?.opIndex ?? 0,
+        replay: processed.replayed,
+        ...(processed.recordedAtMs !== undefined
+            ? { recordedAtMs: processed.recordedAtMs }
+            : {}),
+        ...(processed.cacheIdentity !== undefined
+            ? { cacheIdentity: processed.cacheIdentity }
+            : {}),
     });
 }
 async function* streamResponse(plan, ctx, schema, report) {
@@ -276,9 +291,10 @@ async function* streamResponse(plan, ctx, schema, report) {
     try {
         // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
         for (const push of plan.pushes) {
-            const frame = await processPushCommit(ctx, schema, plan.resolved, plan.header.clientId, push);
+            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/dist/postgres-storage.js

@@ -91,6 +91,12 @@ function serializePushResult(result) {
     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 {
@@ -144,6 +150,12 @@ function deserializePushResult(value) {
     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/push.d.ts

@@ -22,6 +22,13 @@ import type { SyncRequestContext } from './context.js';
 import type { CompiledSchema } from './schema.js';
 import type { ResolvedScopes } from './scopes.js';
 import type { StoredCommit } from './storage.js';
+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;
+}
 export interface AppliedCommitEvent {
     readonly commit: StoredCommit;
 }
@@ -30,3 +37,9 @@ export interface AppliedCommitEvent {
  * atomic apply (§6.4), realtime notification for applied commits.
  */
 export declare function processPushCommit(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame): Promise<PushResultFrame>;
+/**
+ * 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 declare function processPushCommitWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, frame: PushCommitFrame): Promise<ProcessedPushCommit>;

package/dist/push.js

@@ -466,6 +466,25 @@ function resultFrame(clientCommitId, stored, replay) {
         results: [...stored.results],
     };
 }
+function processedPushCommit(clientCommitId, stored, replayed) {
+    return {
+        frame: resultFrame(clientCommitId, stored, replayed),
+        replayed,
+        ...(stored.recordedAtMs !== undefined
+            ? { recordedAtMs: stored.recordedAtMs }
+            : {}),
+        ...(stored.cacheIdentity !== undefined
+            ? { cacheIdentity: stored.cacheIdentity }
+            : {}),
+    };
+}
+function newStoredPushResult(recordedAtMs, result) {
+    return {
+        ...result,
+        recordedAtMs,
+        cacheIdentity: crypto.randomUUID(),
+    };
+}
 function idempotencyCacheMissFrame(clientCommitId, error) {
     return {
         type: 'PUSH_RESULT',
@@ -496,13 +515,24 @@ async function persistRejectedPushResult(storage, partition, clientId, clientCom
     if (canonical === undefined) {
         throw new Error('push rejection finalization did not persist an outcome');
     }
-    return canonical;
+    return {
+        stored: canonical,
+        replayed: canonical.cacheIdentity !== stored.cacheIdentity,
+    };
 }
 /**
  * Process one `PUSH_COMMIT` frame: idempotency replay (§2.3), sequential
  * atomic apply (§6.4), realtime notification for applied commits.
  */
 export async function processPushCommit(ctx, schema, resolved, clientId, frame) {
+    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, schema, resolved, clientId, frame) {
     const { storage, partition } = ctx;
     let persisted;
     try {
@@ -513,12 +543,15 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
             error.code === 'sync.idempotency_cache_miss') {
             // §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)();
     const blobCtx = { store: ctx.blobs, partition };
@@ -541,14 +574,17 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
                 const serializedPersisted = await storage.getPushResult(partition, clientId, frame.clientCommitId);
                 if (serializedPersisted !== undefined) {
                     await tx.rollback();
-                    return resultFrame(frame.clientCommitId, serializedPersisted, true);
+                    return processedPushCommit(frame.clientCommitId, serializedPersisted, true);
                 }
             }
             catch (error) {
                 if (error instanceof SyncError &&
                     error.code === 'sync.idempotency_cache_miss') {
                     await tx.rollback();
-                    return idempotencyCacheMissFrame(frame.clientCommitId, error);
+                    return {
+                        frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+                        replayed: false,
+                    };
                 }
                 throw error;
             }
@@ -580,10 +616,10 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
         if (terminated !== undefined) {
             // §6.3 rejected: only the terminating operation's record; §6.4:
             // every write of the commit rolls back.
-            const stored = {
+            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
@@ -596,9 +632,9 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
             else {
                 await tx.rollback();
                 const canonical = await persistRejectedPushResult(storage, partition, clientId, frame.clientCommitId, stored);
-                return resultFrame(frame.clientCommitId, canonical, canonical !== stored);
+                return processedPushCommit(frame.clientCommitId, canonical.stored, canonical.replayed);
             }
-            return resultFrame(frame.clientCommitId, stored, false);
+            return processedPushCommit(frame.clientCommitId, stored, false);
         }
         const commitSeq = await tx.appendCommit({
             clientId,
@@ -607,7 +643,11 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
             createdAtMs,
             changes,
         });
-        const stored = { 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) {
@@ -618,12 +658,12 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
                 changes,
             });
         }
-        return resultFrame(frame.clientCommitId, stored, false);
+        return processedPushCommit(frame.clientCommitId, stored, false);
     }
     catch (error) {
         await tx.rollback();
         if (error instanceof StorageConstraintError) {
-            const stored = {
+            const stored = newStoredPushResult(createdAtMs, {
                 status: 'rejected',
                 results: [
                     {
@@ -634,9 +674,9 @@ export async function processPushCommit(ctx, schema, resolved, clientId, frame)
                         retryable: false,
                     },
                 ],
-            };
+            });
             const canonical = await persistRejectedPushResult(storage, partition, clientId, frame.clientCommitId, stored);
-            return resultFrame(frame.clientCommitId, canonical, canonical !== stored);
+            return processedPushCommit(frame.clientCommitId, canonical.stored, canonical.replayed);
         }
         throw error;
     }

package/dist/seed.d.ts

@@ -26,9 +26,34 @@ export interface SeedTarget {
     /** The client commit id (default `'seed-commit-1'`). */
     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 declare class SeedMutationError extends Error {
+    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);
+}
 /**
  * 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 declare function seedMutations(config: SyncServerConfig, target: SeedTarget, mutations: readonly SeedMutation[]): Promise<void>;

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/storage.d.ts

@@ -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 {

package/package.json

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

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/postgres-storage.ts

@@ -193,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 {
@@ -223,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) => {
@@ -251,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,
   };
 }

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/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/storage.ts

@@ -70,6 +70,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[];
 }