@syncular/server 0.15.21 → 0.15.23

package/README.md

@@ -173,10 +173,49 @@ 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.
 
+## Trusted relational-index lookups for authoritative commands
+
+`scanRows` is a Syncular scope-index scan, never an unscoped administrative
+query. Passing an empty or omitted `scopeFilter` throws the exported
+`StorageQueryError` with `code: 'sync.storage.scan_requires_scope'` on
+SQLite, PostgreSQL, and D1.
+
+An authoritative command that needs an exact alternate lookup can instead use
+the optional `storage.scanRowsByIndex(partition, query)` or transactional
+`tx.scanRowsByIndex(query)` capability. The query names one declared
+`TableSchema.indexes` entry, supplies one exact value per index column, uses an
+exclusive `afterRowId`, and has a required limit from 1 through 1,000. All
+shipped adapters implement it; transaction reads see staged writes and deletes.
+It requires a materialized table.
+
+This is a trusted `@syncular/server` storage capability, not SSP2: it creates no
+scope variable, named-query obligation, subscription descriptor, or client
+authority. Never expose table/index/value selection through a client-controlled
+route. Custom adapters may omit the additive method; authoritative commands
+must check for it and fail closed. See the public
+[storage lookup guide](https://syncular.dev/server-storage/#choosing-the-right-row-lookup)
+for a user-scoped key-grant table revoked through a Workspace index and for the
+atomic reverse-index/queue fallback required by ordered or derived lookups.
+
 ## Structured events (the ops seam)
 
 One optional interface, `SyncularServerEvents`, carries every

package/dist/d1-storage.d.ts

@@ -1,5 +1,5 @@
 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 interface D1PreparedStatement {
     bind(...values: unknown[]): D1PreparedStatement;
     first<T = Record<string, unknown>>(): Promise<T | null>;
@@ -40,6 +40,7 @@ export declare class D1ServerStorage 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/d1-storage.js

@@ -42,10 +42,11 @@ var _a;
  */
 import { decodeRow } from '@syncular/core';
 import { syncError } from './errors.js';
-import { commitWindowPageSql, deleteRowSql, dropTableDdl, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
+import { commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { asUint8Array, collectCommitWindowPage, deserializePushResult, serializePushResult, sqliteDdlStatements, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
+import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
 function relationalValuesEqual(left, right) {
     if (left instanceof Uint8Array && right instanceof Uint8Array) {
         return (left.length === right.length &&
@@ -100,6 +101,7 @@ class D1Transaction {
     }
     async scanRows(query) {
         this.#assertOpen();
+        assertScopeIndexedScan(query);
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];
         if (firstVariable === undefined)
@@ -149,6 +151,43 @@ class D1Transaction {
             .sort((left, right) => left.rowId.localeCompare(right.rowId))
             .slice(0, query.limit);
     }
+    async scanRowsByIndex(query) {
+        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();
+        const rows = new Map(records.map((record) => {
+            const row = toStoredRow(record);
+            return [row.rowId, row];
+        }));
+        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() {
         this.#assertOpen();
         if (!this.#commitValidationSerialized) {
@@ -575,6 +614,7 @@ export class D1ServerStorage {
         return commits;
     }
     async scanRows(partition, query) {
+        assertScopeIndexedScan(query);
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];
         if (firstVariable === undefined)
@@ -614,6 +654,16 @@ export class D1ServerStorage {
         }
         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 { results } = await this.#db
+            .prepare(statement.sql)
+            .bind(...statement.params)
+            .all();
+        return results.map(toStoredRow);
+    }
     async getClientRecord(partition, clientId) {
         const record = await this.#db
             .prepare('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? AND client_id=?')

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

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

package/dist/index.js

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

package/dist/postgres-storage.d.ts

@@ -1,6 +1,6 @@
 import { type PgExecutor } from './pg-executor.js';
 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';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -50,6 +50,7 @@ export declare class PostgresServerStorage 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/postgres-storage.js

@@ -1,8 +1,9 @@
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
-import { commitWindowPageSql, deleteRowSql, dropTableDdl, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, 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_POSTGRES, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
+import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -90,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 {
@@ -143,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,
     };
 }
@@ -213,6 +226,12 @@ async function getRowOn(q, compiled, partition, rowId) {
     const record = rows[0];
     return record === undefined ? undefined : toStoredRow(record);
 }
+async function scanRowsByIndexOn(q, compiled, partition, query) {
+    const index = resolveIndexRowScan(compiled, query);
+    const statement = indexRowPageStatement(compiled, index, query.values, partition, query.afterRowId, query.limit, 'postgres');
+    const { rows } = await q.query(statement.sql, statement.params);
+    return rows.map(toStoredRow);
+}
 async function writeRowOn(q, compiled, partition, row) {
     await q.query(upsertSql(compiled, 'postgres'), upsertValues(compiled, partition, row, 'postgres'));
     await q.query('DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$2 AND row_id=$3', [partition, compiled.name, row.rowId]);
@@ -247,6 +266,7 @@ class PostgresTransaction {
     }
     async scanRows(query) {
         this.#assertOpen();
+        assertScopeIndexedScan(query);
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];
         if (firstVariable === undefined)
@@ -285,6 +305,10 @@ class PostgresTransaction {
         }
         return rows;
     }
+    scanRowsByIndex(query) {
+        this.#assertOpen();
+        return scanRowsByIndexOn(this.#client, this.#resolveTable(query.table), this.#partition, query);
+    }
     async lockPartitionForCommitValidation() {
         this.#assertOpen();
         await this.#client.query(`INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 0)
@@ -673,6 +697,7 @@ export class PostgresServerStorage {
         return commits;
     }
     async scanRows(partition, query) {
+        assertScopeIndexedScan(query);
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];
         if (firstVariable === undefined)
@@ -717,6 +742,9 @@ export class PostgresServerStorage {
         }
         return rows;
     }
+    scanRowsByIndex(partition, query) {
+        return scanRowsByIndexOn(this.#exec, this.table(query.table), partition, query);
+    }
     async getClientRecord(partition, clientId) {
         const { rows } = await this.#exec.query('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=$1 AND client_id=$2', [partition, clientId]);
         const record = rows[0];

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

@@ -44,7 +44,7 @@
  *   NOT NULL per the schema.
  */
 import { type RowColumn, type RowValue } from '@syncular/core';
-import type { CompiledSchema, CompiledTable } from './schema.js';
+import type { CompiledSchema, CompiledTable, IndexSchema } from './schema.js';
 import type { StoredRow } from './storage.js';
 export type RelationalDialect = 'sqlite' | 'postgres';
 export declare const SYNC_PARTITION_COLUMN = "_sync_partition";
@@ -100,6 +100,16 @@ export declare function upsertSql(table: CompiledTable, dialect: RelationalDiale
  * `toStoredRow` converters keep working. Params: [partition, rowId].
  */
 export declare function selectRowSql(table: CompiledTable, dialect: RelationalDialect): string;
+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 declare function indexRowPageStatement(table: CompiledTable, index: IndexSchema, values: readonly RowValue[], partition: string, afterRowId: string | null | undefined, limit: number, dialect: RelationalDialect): IndexRowPageStatement;
 /**
  * One-round-trip page scan for `scanRows`: candidates from the inverted
  * scope index (ordered + LIMITed at the covering `sync_row_scopes` PK —

package/dist/relational-rows.js

@@ -243,6 +243,35 @@ export function selectRowSql(table, dialect) {
     const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];
     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]}`;
 }
+/**
+ * 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, index, values, partition, afterRowId, limit, dialect) {
+    const params = [partition];
+    const placeholder = () => 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/dist/schema.js

@@ -61,6 +61,9 @@ export function compileSchema(schema) {
                 throw new Error(`table ${table.name}: duplicate index ${JSON.stringify(index.name)}`);
             }
             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(`table ${table.name}: index ${JSON.stringify(index.name)} names unknown column ${JSON.stringify(column)}`);

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