@spooky-sync/core 0.0.1-canary.207 → 0.0.1-canary.209

package/dist/index.d.ts

@@ -12,12 +12,18 @@ declare abstract class AbstractDatabaseService {
   protected logger: Logger$1;
   protected events: DatabaseEventSystem;
   /**
-   * Per-query deadline in ms; `0` disables. Only the remote service sets this
-   * (see `RemoteDatabaseService`) — a local query can be legitimately slow and
-   * has its own retry ladders, and there is no half-open-socket failure mode
-   * for an in-process engine.
+   * Per-query deadline in ms; `0` disables. The remote service sets it from
+   * `queryTimeoutMs` (see `RemoteDatabaseService`), the local one from
+   * `localOpTimeoutMs` (see `LocalDatabaseService`): a local query can be
+   * legitimately slow, but it must never be endless - every query waits on the
+   * previous link of {@link query}'s chain, and one that never settled wedged
+   * every later local op behind it.
    */
   protected queryTimeoutMs: number;
+  /** The error a deadline expiry rejects with; the local service substitutes
+   *  its typed `LocalOpTimeoutError`. "timed out" in the message is
+   *  load-bearing either way: `classifySyncError` keys off it. */
+  protected timeoutError(_query: string): Error;
   protected abstract eventType: typeof DatabaseEventTypes.LocalQuery | typeof DatabaseEventTypes.RemoteQuery;
   constructor(client: Surreal$1, logger: Logger$1, events: DatabaseEventSystem);
   abstract connect(): Promise<void>;
@@ -256,6 +262,14 @@ interface StreamUpdate {
   queryHash: string;
   localArray: RecordVersionArray;
   op?: 'CREATE' | 'UPDATE' | 'DELETE';
+  /**
+   * Client-internal: not from the circuit. A membership-only change that
+   * needed no fetch is re-materialized through this same path so it cannot
+   * race a real update (DataModule.scheduleRematerialize). Carries the last
+   * known `localArray`; consumers that describe an INGEST (persist, metrics,
+   * devtools events) skip it.
+   */
+  synthetic?: boolean;
   /**
    * End-to-end ingest latency for the WASM call that produced this update,
    * in milliseconds. Populated by StreamProcessorService.ingest. Undefined
@@ -734,6 +748,22 @@ declare class DataModule<S extends SchemaStructure> {
    * Handle stream updates from DBSP (via CacheModule)
    */
   onStreamUpdate(update: StreamUpdate): Promise<void>;
+  /** Coalesce `update` onto the query's trailing timer (see onStreamUpdate). */
+  private queueStreamUpdate;
+  /**
+   * Re-materialize + notify a query whose MEMBERSHIP changed without any row
+   * needing to be fetched, i.e. without the SSP stream update that normally
+   * carries the notify. That is every row this client wrote itself: the local
+   * CREATE memoized it at `_00_rv = 1`, the server publishes it at 1, so the
+   * sync engine rightly fetches nothing - and then nobody told the subscribers
+   * that `remoteArray` now holds the id. The row appeared on reload only.
+   *
+   * Routed through the same per-query debounce as a real stream update, so it
+   * cannot race one: a pending real update already materializes against the
+   * current `remoteArray` and wins. The synthetic update re-uses the circuit's
+   * last `localArray` and skips the persist/metrics that describe an ingest.
+   */
+  scheduleRematerialize(queryHash: string): void;
   /**
    * Process a query's pending (debounced) stream update NOW instead of on the
    * trailing edge. Called by the sync engine before it flips a query back to
@@ -794,6 +824,8 @@ declare class DataModule<S extends SchemaStructure> {
   private pendingIdsAt;
   private pendingIdsInflight;
   private static readonly PENDING_IDS_TTL_MS;
+  private pendingIdsGen;
+  private static readonly PENDING_IDS_MAX_REREADS;
   /** Drop the cached outbox ids. Cheap; call it on anything that could change
    *  `_00_pending_mutations`. */
   private invalidatePendingIds;
@@ -957,7 +989,8 @@ declare class DataModule<S extends SchemaStructure> {
     deletes: Set<string>;
   }>;
   /** The uncached read. Also the reload path after an invalidation, so the ids
-   *  still survive a reload exactly as before. */
+   *  still survive a reload exactly as before. `gen` is the generation the read
+   *  was issued under; the result is cached only if it is still current. */
   private readPendingRecordIds;
   /** True while ≥1 live subscriber is watching this query (refcount guard). */
   hasSubscribers(hash: string): boolean;
@@ -2640,6 +2673,36 @@ declare class Sp00kyClient<S extends SchemaStructure> {
 /** True when `a` is a valid version strictly greater than valid version `b`. */
 declare function semverGt(a: unknown, b: unknown): boolean;
 //#endregion
+//#region src/services/database/errors.d.ts
+/**
+ * A local-store operation that did not answer within its deadline.
+ *
+ * The local write path (`db.create` / `db.update` / `db.delete`, every local
+ * query behind them) used to have no deadline anywhere: the SQLite worker
+ * transport parks a call until the worker replies, the surrealdb engine's
+ * query chain waits on the previous link, and `withRetry` retries without a
+ * clock. One op that never settled (a worker starved behind a long select, a
+ * lock verification awaiting `navigator.locks.query()` forever) left the
+ * caller's promise pending for the tab's lifetime - a chat composer that never
+ * re-enabled, a call that never got past "Connecting".
+ *
+ * The message says "timed out" on purpose: `classifySyncError` keys off it and
+ * treats the failure as transient (re-queue), never as an application error
+ * that rolls the mutation back. `retryable: false` keeps `withRetry` from
+ * spinning on it: the op is still running in the engine, retrying queues a
+ * second copy behind it.
+ */
+declare class LocalOpTimeoutError extends Error {
+  readonly name = "LocalOpTimeoutError";
+  readonly retryable = false;
+  readonly op: string;
+  readonly timeoutMs: number;
+  constructor(op: string, timeoutMs: number);
+}
+/** Default deadline for one local-store operation. Generous: a cold 4k-row
+ *  select on a throttled tab is seconds, not tens of seconds. */
+declare const DEFAULT_LOCAL_OP_TIMEOUT_MS = 30000;
+//#endregion
 //#region src/utils/index.d.ts
 declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
 /**
@@ -2652,4 +2715,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };