@syncular/server 0.15.21 → 0.15.23

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. */
@@ -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[];
 }
 
@@ -113,6 +117,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 +196,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 +309,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,