@syncular/server 0.15.21 → 0.15.22

package/README.md

@@ -177,6 +177,30 @@ The task-oriented [concurrency and conflict-correction guide](https://syncular.d
 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/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).
  *
@@ -213,6 +214,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 +254,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 +293,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 +685,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 +730,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/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/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 {
@@ -102,6 +102,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 +175,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 +252,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.22",
   "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.22"
   },
   "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/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';

package/src/postgres-storage.ts

@@ -47,6 +47,7 @@ import {
   commitWindowPageSql,
   deleteRowSql,
   dropTableDdl,
+  indexRowPageStatement,
   layoutsOf,
   migratePayload,
   parseLayouts,
@@ -73,6 +74,7 @@ import type {
   CommitMetadata,
   CommitMetadataQuery,
   CommitWindowQuery,
+  IndexRowScanQuery,
   NewCommit,
   RowScanQuery,
   ScopeActivityQuery,
@@ -88,6 +90,7 @@ import {
   isPostgresConstraintError,
   StorageConstraintError,
 } from './storage-errors';
+import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query';
 
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
@@ -374,6 +377,26 @@ async function getRowOn(
   return record === undefined ? undefined : toStoredRow(record);
 }
 
+async function scanRowsByIndexOn(
+  q: PgQueryable,
+  compiled: CompiledTable,
+  partition: string,
+  query: IndexRowScanQuery,
+): Promise<StoredRow[]> {
+  const index = resolveIndexRowScan(compiled, query);
+  const statement = indexRowPageStatement(
+    compiled,
+    index,
+    query.values,
+    partition,
+    query.afterRowId,
+    query.limit,
+    'postgres',
+  );
+  const { rows } = await q.query<RowRecord>(statement.sql, statement.params);
+  return rows.map(toStoredRow);
+}
+
 async function writeRowOn(
   q: PgQueryable,
   compiled: CompiledTable,
@@ -437,6 +460,7 @@ class PostgresTransaction implements StorageTransaction {
 
   async scanRows(query: RowScanQuery): Promise<StoredRow[]> {
     this.#assertOpen();
+    assertScopeIndexedScan(query);
     const variables = Object.keys(query.scopeFilter).sort();
     const firstVariable = variables[0];
     if (firstVariable === undefined) return [];
@@ -473,6 +497,16 @@ class PostgresTransaction implements StorageTransaction {
     return rows;
   }
 
+  scanRowsByIndex(query: IndexRowScanQuery): Promise<StoredRow[]> {
+    this.#assertOpen();
+    return scanRowsByIndexOn(
+      this.#client,
+      this.#resolveTable(query.table),
+      this.#partition,
+      query,
+    );
+  }
+
   async lockPartitionForCommitValidation(): Promise<void> {
     this.#assertOpen();
     await this.#client.query(
@@ -1012,6 +1046,7 @@ export class PostgresServerStorage implements ServerStorage {
   }
 
   async scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]> {
+    assertScopeIndexedScan(query);
     const variables = Object.keys(query.scopeFilter).sort();
     const firstVariable = variables[0];
     if (firstVariable === undefined) return [];
@@ -1054,6 +1089,18 @@ export class PostgresServerStorage implements ServerStorage {
     return rows;
   }
 
+  scanRowsByIndex(
+    partition: string,
+    query: IndexRowScanQuery,
+  ): Promise<StoredRow[]> {
+    return scanRowsByIndexOn(
+      this.#exec,
+      this.table(query.table),
+      partition,
+      query,
+    );
+  }
+
   async getClientRecord(
     partition: string,
     clientId: string,

package/src/relational-rows.ts

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

package/src/schema.ts

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

package/src/sqlite-storage.ts

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

package/src/storage-errors.ts

@@ -13,6 +13,42 @@ export class StorageConstraintError extends Error {
   }
 }
 
+/** 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';
+
+const STORAGE_QUERY_MESSAGES: Readonly<Record<StorageQueryErrorCode, string>> =
+  {
+    '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 {
+  override readonly name = 'StorageQueryError';
+  readonly code: StorageQueryErrorCode;
+
+  constructor(code: StorageQueryErrorCode) {
+    super(STORAGE_QUERY_MESSAGES[code]);
+    this.code = code;
+  }
+}
+
 interface DriverError {
   readonly code?: unknown;
   readonly errno?: unknown;

package/src/storage-query.ts

@@ -0,0 +1,48 @@
+import type { ScopeMap } from '@syncular/core';
+import type { CompiledTable, IndexSchema } from './schema';
+import type { IndexRowScanQuery, RowScanQuery } from './storage';
+import { StorageQueryError } from './storage-errors';
+
+/** Fail loudly instead of making an unsupported unscoped scan look empty. */
+export function assertScopeIndexedScan(query: RowScanQuery): void {
+  const scopeFilter = (
+    query as RowScanQuery & { readonly scopeFilter?: ScopeMap | null }
+  ).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: CompiledTable,
+  query: IndexRowScanQuery,
+): IndexSchema {
+  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/src/storage.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';
 
 /** The current stored state of a synced row. */
@@ -113,6 +113,26 @@ export interface RowScanQuery {
   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;
@@ -172,6 +192,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.
@@ -279,6 +305,16 @@ export interface ServerStorage {
   /** 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,