@spooky-sync/core 0.0.1-canary.154 → 0.0.1-canary.155

package/dist/index.d.ts

@@ -139,6 +139,7 @@ declare class StreamProcessorService {
   private sessionAuth;
   private stateKeySuffix;
   private stateGeneration;
+  private persistState;
   constructor(events: EventSystem<StreamProcessorEvents>, db: LocalStore, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
@@ -199,6 +200,8 @@ declare class StreamProcessorService {
    * afterwards (a fresh circuit default-denies every table).
    */
   reset(): Promise<void>;
+  /** Toggle circuit-state persistence (shared-tabs follower/leader role). */
+  setPersistenceEnabled(enabled: boolean): void;
   loadState(): Promise<void>;
   /**
    * Seed per-table `select` permission predicates ({ [table]: whereText }).
@@ -261,18 +264,39 @@ interface CacheRecord {
  * Single responsibility: Handle all local storage operations and DBSP ingestion.
  * This module acts as the bridge between data operations and persistence.
  */
+/** One ingested change, in exactly the shape `ingestMany` consumes. Shared
+ *  with the tabs protocol so a leader can relay its ingests to followers. */
+interface CacheIngestTuple {
+  table: string;
+  op: 'CREATE' | 'UPDATE' | 'DELETE';
+  id: string;
+  record: Record<string, unknown>;
+}
 declare class CacheModule implements StreamUpdateReceiver {
   private local;
   private streamProcessor;
   private logger;
   private streamUpdateCallback;
   private versionLookups;
+  /** Shared-tabs leader: fan every committed ingest out to follower circuits.
+   *  Fired AFTER the local tx (the rows are already in the shared store, so a
+   *  follower only needs the circuit feed). Never set on followers. */
+  private ingestRelay;
   constructor(local: LocalStore, streamProcessor: StreamProcessorService, streamUpdateCallback: (update: StreamUpdate) => void, logger: Logger$1);
   /**
    * Implements StreamUpdateReceiver interface
    * Called directly by StreamProcessor when views change
    */
   onStreamUpdate(update: StreamUpdate): void;
+  setIngestRelay(cb: ((tuples: CacheIngestTuple[]) => void) | null): void;
+  /**
+   * Shared-tabs follower: feed relayed tuples into THIS tab's circuit only.
+   * The rows are already in the shared store (the leader wrote them), so no
+   * local write happens here; the normal chain then runs: SSP -> stream update
+   * -> DataModule debounce -> materializeRecords (re-reads via the port
+   * transport) -> this tab's subscriptions fire with this tab's hashes.
+   */
+  applyRelayedIngest(tuples: CacheIngestTuple[]): void;
   lookup(recordId: string): number;
   /** Drop the version cache on a bucket switch — a stale version would make
    *  the sync diff skip fetching a body the new bucket legitimately needs. */
@@ -322,6 +346,9 @@ declare class DataModule<S extends SchemaStructure> {
   private local;
   private schema;
   private streamDebounceTime;
+  /** Tab identity baked into mutation ids (shared-tabs rollback routing);
+   *  undefined in solo mode, where mutation-id falls back to a session id. */
+  private tabId;
   private activeQueries;
   private pendingQueries;
   private subscriptions;
@@ -367,6 +394,9 @@ declare class DataModule<S extends SchemaStructure> {
    * registered queries will get fresh, session-scoped IDs.
    */
   setSessionId(sessionId: string): void;
+  /** Shared-tabs: bake this tab's identity into mutation ids so a rollback of
+   *  a follower's mutation routes back to the tab that made it. */
+  setTabId(tabId: string): void;
   /**
    * Update the authenticated user record id. Pass `null` on sign-out.
    * Read by `Sp00kySync.listRefTable()` so the LIVE subscription and
@@ -625,6 +655,98 @@ declare class DataModule<S extends SchemaStructure> {
  * Parse update options to generate push event options
  */
 //#endregion
+//#region src/services/tabs/protocol.d.ts
+type TabId = string;
+type TabRole = 'solo' | 'leader' | 'follower';
+/** Broker pings every tab at this cadence. */
+
+/** Matches `CacheIngestTuple` (modules/cache): exactly what `ingestMany`
+ *  consumes, so relayed batches feed follower circuits without reshaping. */
+interface IngestTuple {
+  table: string;
+  op: 'CREATE' | 'UPDATE' | 'DELETE';
+  id: string;
+  record: Record<string, unknown>;
+}
+type FollowerToLeaderMessage = {
+  type: 'sync-hello';
+  tabId: TabId;
+}
+/** The follower committed an outbox row (through the shared store) and the
+ *  leader should drain it. Idempotent; a new leader's loadFromDatabase is
+ *  the backstop for a notify lost in a failover window. */ | {
+  type: 'mutation-enqueued';
+  mutationId: string;
+} | {
+  type: 'request-poll';
+};
+type LeaderToFollowerMessage = {
+  type: 'db-ready';
+  leadershipId: number;
+  bucketId: string;
+  storageHealth: StorageHealth;
+}
+/** Every ingest the leader's CacheModule committed, so follower circuits
+ *  stay live without their own fetch. seq detects gaps. */ | {
+  type: 'ingest-relay';
+  tuples: IngestTuple[];
+  leadershipId: number;
+  seq: number;
+}
+/** A `_00_list_ref` LIVE event, relayed verbatim. Each follower resolves the
+ *  queryId against its own DataModule and ignores foreign queries. */ | {
+  type: 'list-ref-change';
+  action: 'CREATE' | 'UPDATE' | 'DELETE';
+  queryId: string;
+  recordId: string;
+  version: number;
+  parent: boolean;
+}
+/** The leader's drain rolled back a mutation owned by this tab. */ | {
+  type: 'mutation-rolled-back';
+  mutationId: string;
+  recordId: string;
+  eventType: 'create' | 'update' | 'delete';
+  error: string;
+};
+//#endregion
+//#region src/services/tabs/coordinator.d.ts
+/** Leader-side fan-out surface handed to the sync layer. The sync router
+ *  (modules/sync/tab-router.ts) registers itself as the message handler. */
+declare class LeaderSyncHub {
+  readonly leadershipId: number;
+  private logger;
+  private followers;
+  private seq;
+  onFollowerMessage: ((tabId: TabId, msg: FollowerToLeaderMessage) => void) | null;
+  onFollowerDetached: ((tabId: TabId) => void) | null;
+  constructor(leadershipId: number, logger: Logger$1);
+  attach(tabId: TabId, port: MessagePort): void;
+  detach(tabId: TabId): void;
+  detachAll(): void;
+  sendTo(tabId: TabId, msg: LeaderToFollowerMessage): void;
+  broadcast(msg: LeaderToFollowerMessage, exceptTabId?: TabId): void;
+  /** Stamped ingest relay; seq lets followers detect gaps. */
+  relayIngest(tuples: IngestTuple[], exceptTabId?: TabId): void;
+  get followerCount(): number;
+  get relayedBatches(): number;
+}
+/** Follower half of the syncPort. Queues while detached (leaderless window)
+ *  and flushes on rebind; a lost-in-flight mutation notify is additionally
+ *  backstopped by the new leader reloading the shared outbox from the store. */
+declare class SyncForwarder {
+  private tabId;
+  private port;
+  private queued;
+  onLeaderMessage: ((msg: LeaderToFollowerMessage) => void) | null;
+  constructor(tabId: TabId);
+  rebind(port: MessagePort): void;
+  unbind(): void;
+  private post;
+  mutationEnqueued(mutationId: string): void;
+  requestPoll(): void;
+}
+//#endregion
 //#region src/modules/sync/sync.d.ts
 /**
  * Tunables for `Sp00kySync` construction.
@@ -675,6 +797,10 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private wasDisconnected;
   events: SyncEventSystem;
   private currentUserId;
+  private tabRole;
+  private tabId;
+  private hub;
+  private forwarder;
   private refMode;
   private readonly anonLiveEnabled;
   private currentLiveQueryUuid;
@@ -732,6 +858,25 @@ declare class Sp00kySync<S extends SchemaStructure> {
    * @throws Error if already initialized.
    */
   init(): Promise<void>;
+  /** Set BEFORE init(): shapes what init boots (a follower loads no outbox and
+   *  never starts LIVE; its own registration/poll paths stay untouched). */
+  setTabContext(role: 'solo' | 'leader' | 'follower', tabId: string | null): void;
+  /** Leader duties: drain the shared outbox, own the single list_ref LIVE,
+   *  relay LIVE events and rollbacks to followers via `hub`. Idempotent for a
+   *  boot-time leader; a runtime promotion (failover) reloads the outbox,
+   *  which now holds EVERY tab's rows, and restarts LIVE under this session. */
+  promoteToLeader(hub: LeaderSyncHub): Promise<void>;
+  /** Follower duties: no outbox drain, no LIVE. Mutations forward to the
+   *  leader; everything else (registration, per-query sync, poll) runs
+   *  against this tab's own remote session as usual. */
+  demoteToFollower(forwarder: SyncForwarder): void;
+  /** A forwarded outbox row from a follower: load + drain it. Idempotent. */
+  enqueueForwardedMutation(mutationId: string): Promise<void>;
+  /** A relayed `_00_list_ref` LIVE event: resolve against THIS tab's queries
+   *  and run the exact same handling the LIVE subscription would have. */
+  private applyRelayedListRefChange;
+  /** One immediate poll cycle (failover convergence). */
+  forcePollRound(): Promise<void>;
   /**
    * Quiesce all sync activity ahead of a local-bucket switch. After this
    * resolves, nothing in the sync module writes to the local store: the poll
@@ -1248,6 +1393,10 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private logger;
   auth: AuthService<S>;
   streamProcessor: StreamProcessorService;
+  private tabsCoordinator;
+  private sharedActive;
+  /** Current shared-tabs role, or null when the feature is off/fell back. */
+  get tabRole(): TabRole | null;
   get remoteClient(): surrealdb0.Surreal;
   get localClient(): unknown;
   get pendingMutationCount(): number;
@@ -1275,6 +1424,8 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    */
   subscribeToStorageHealth(cb: (health: StorageHealth) => void): () => void;
   constructor(config: Sp00kyConfig<S>);
+  /** The shared-tabs role machinery, wired to this client's modules. */
+  private buildTabsCoordinator;
   /**
    * Setup direct callbacks instead of event subscriptions
    */