@spooky-sync/core 0.0.1-canary.204 → 0.0.1-canary.205

package/dist/index.d.ts

@@ -286,10 +286,34 @@ type StreamProcessorEvents = {
 interface StreamUpdateReceiver {
   onStreamUpdate(update: StreamUpdate): void;
 }
+/** One row change in the shape `ingestMany` consumes. */
+interface IngestRecord {
+  table: string;
+  /** `MERGE` overlays the given fields on the stored row (projection widening). */
+  op: 'CREATE' | 'UPDATE' | 'DELETE' | 'MERGE';
+  id: string;
+  record: any;
+}
+/**
+ * What the boot-time prime needs from the client: which tables to walk, how
+ * to recognise a snapshot written under a different schema, and which rows'
+ * local `_00_rv` must not be reported as the server's.
+ */
+interface CircuitPrimeContext {
+  tables: string[];
+  schemaHash: string;
+  /** Encoded ids with an unsettled local mutation (their `_00_rv` was bumped
+   *  locally and may exceed the server's next version). */
+  pendingIds: Set<string>;
+  /** Receives every `(id, rv)` the prime put into the circuit, per table, so
+   *  the sync layer can skip re-downloading bodies it already has. */
+  onVersions?: (table: string, entries: [string, number][]) => void;
+}
+/** Storage key of the circuit snapshot inside the local store. */
+
 declare class StreamProcessorService {
   events: EventSystem<StreamProcessorEvents>;
   private db;
-  private persistenceClient;
   private logger;
   private processor;
   private isInitialized;
@@ -297,15 +321,21 @@ declare class StreamProcessorService {
   private batching;
   private batchBuffer;
   private sessionAuth;
-  private stateKeySuffix;
   private stateGeneration;
   private persistState;
   private persistCircuit;
   private checkpointMs;
   private checkpointTimer;
   private snapshotDirty;
-  private pagehideHandler;
-  constructor(events: EventSystem<StreamProcessorEvents>, db: LocalStore, persistenceClient: PersistenceClient, logger: Logger);
+  private dirtyRows;
+  private hideHandler;
+  private checkpointInFlight;
+  private projection;
+  private primed;
+  private schemaHash;
+  private widenQueue;
+  private widenPending;
+  constructor(events: EventSystem<StreamProcessorEvents>, db: LocalStore, logger: Logger);
   /**
    * Add a receiver for stream updates.
    * Multiple receivers can be registered (DataManager, DevTools, etc.)
@@ -314,23 +344,21 @@ declare class StreamProcessorService {
   private notifyUpdates;
   private dispatchUpdates;
   /**
-   * Ingest a batch of record changes as a single bulk operation, firing only
-   * one coalesced `StreamUpdate` per affected query once every record has been
-   * ingested (instead of one update per record). Use this whenever multiple
-   * records land at once — e.g. sync fetching N missing rows — so a list query
-   * re-runs and the UI re-renders once for the whole batch rather than
-   * row-by-row.
+   * Ingest a batch of record changes, firing one coalesced `StreamUpdate` per
+   * affected query once every record has been ingested. Use this whenever
+   * multiple records land at once (sync fetching N rows, the boot prime).
+   *
+   * The batch is fed to the wasm side in chunks of {@link INGEST_CHUNK}: one
+   * circuit step per chunk (a step walks every registered view, so per-record
+   * ingest paid that fixed cost N times), but never the whole batch at once,
+   * because the wasm side has to hold every parsed row of a call at the same
+   * time and wasm32 dlmalloc never returns that peak.
    *
-   * Internally opens a coalescing window, ingests each record, then flushes;
-   * processor state is persisted once for the whole batch. No-op for an empty
-   * batch.
+   * Returns the records that were ingested. A chunk that fails is reported
+   * and skipped, not retried (a retry would double-apply whatever the failed
+   * step already committed), and the remaining chunks still run.
    */
-  ingestMany(records: Array<{
-    table: string;
-    op: 'CREATE' | 'UPDATE' | 'DELETE';
-    id: string;
-    record: any;
-  }>): void;
+  ingestMany(records: IngestRecord[]): IngestRecord[];
   /**
    * Open a coalescing window. While open, the per-record stream updates
    * emitted by `ingest` are buffered (one entry per queryHash) instead of
@@ -352,17 +380,16 @@ declare class StreamProcessorService {
    * This must be called before using other methods.
    */
   init(): Promise<void>;
-  /** Route the persisted circuit snapshot to a per-bucket key. */
-  setStateKeySuffix(bucketId: string): void;
-  private stateKey;
   /**
    * Drop the current WASM processor and start a fresh, empty circuit. Used on
    * local-bucket switches: the old circuit holds the previous user's rows AND
    * views registered with the previous `$auth` context, so neither may survive.
-   * Deliberately does NOT `loadState()` — a persisted snapshot references views
-   * under a dead sessionId salt; the DataModule rebind re-registers every live
-   * view against this fresh processor. Caller must re-seed `setPermissions`
-   * afterwards (a fresh circuit default-denies every table).
+   * Deliberately loads nothing: the snapshot in the store being swapped away
+   * from belongs to the previous bucket; the caller primes the new bucket's
+   * circuit (`primeFromLocal`) once its store is open, and the DataModule
+   * rebind re-registers every live view against this fresh processor. Caller
+   * must re-seed `setPermissions` afterwards (a fresh circuit default-denies
+   * every table).
    */
   reset(): Promise<void>;
   /**
@@ -379,21 +406,61 @@ declare class StreamProcessorService {
   /** Toggle circuit-state persistence (shared-tabs follower/leader role). */
   setPersistenceEnabled(enabled: boolean): void;
   /**
-   * Opt into snapshot persistence (`persistCircuit`). Off by default: see the
-   * `persistCircuit` field comment for why per-ingest snapshots were removed.
-   * Must be called before `init()` for a snapshot to be restored at boot.
+   * Snapshot persistence (`persistCircuit`). When on, the circuit's store is
+   * written to the local store on a checkpoint interval and when the page
+   * goes hidden, and restored by {@link primeFromLocal} on the next boot.
    */
   configureCircuitPersistence(enabled: boolean, checkpointMs?: number): void;
   /**
-   * Record that the circuit changed. Cheap and O(1), the expensive snapshot is
-   * deferred to the checkpoint timer, and skipped entirely when
-   * `persistCircuit` is off (the default).
+   * Field projection (`circuitProjection`, default on). Takes effect on the
+   * next processor (`init`/`reset`) and on rows written after that.
+   */
+  configureProjection(enabled: boolean): void;
+  private applyProjection;
+  /** Resolves once the boot-time prime has finished (or was skipped). */
+  whenPrimed(): Promise<void>;
+  /**
+   * Fill the circuit from the LOCAL store, in the background.
+   *
+   * With a usable snapshot: install it under whatever views have registered
+   * meanwhile (`load_store_state` re-primes them), then `reconcile` each table
+   * against the store's `(id, rv)` list so rows deleted since the checkpoint
+   * are stepped out and only rows added or changed since are read back and
+   * ingested. Without one: read every row and ingest it, chunked.
+   *
+   * Either way the circuit ends up equal to the local store without touching
+   * the network, so the first sync diff is a real delta rather than "fetch
+   * everything". The returned promise never rejects; `whenPrimed` gates on it.
+   */
+  primeFromLocal(ctx: CircuitPrimeContext): Promise<void>;
+  private runPrime;
+  /** Publish wasm updates produced outside an ingest (restore, reconcile). */
+  private dispatchWasmUpdates;
+  /**
+   * Record that the circuit changed by `rows` rows. Cheap; the snapshot is
+   * deferred to the checkpoint timer and skipped entirely when `persistCircuit`
+   * is off.
    */
   private markSnapshotDirty;
   private startCheckpoints;
-  /** Stop checkpointing and drop the `pagehide` listener. */
+  /** Stop checkpointing and drop the visibility listeners. */
   stopCheckpoints(): void;
-  loadState(): Promise<void>;
+  /**
+   * Write the circuit's store to the local store as a snapshot. Compacts the
+   * row arena first when dead bytes outweigh live ones. Serialised: a second
+   * call while one is in flight joins it. No-op unless persistence is on, this
+   * tab owns the store, and the engine can hold a snapshot.
+   */
+  checkpoint(reason?: string): Promise<void>;
+  private runCheckpoint;
+  /**
+   * Projection widening: a newly registered view evaluates fields that rows
+   * already in the circuit were stored without. Merge just those fields in,
+   * table by table, from the local store. The view registered against what
+   * was present and converges as the merges step through.
+   */
+  private scheduleWiden;
+  private runWiden;
   /**
    * Seed per-table `select` permission predicates ({ [table]: whereText }).
    * Must run after the processor exists and before any `register_view`, else
@@ -411,13 +478,12 @@ declare class StreamProcessorService {
    * "requires $auth but registration params lack it".
    */
   setSessionAuth(authId: string | null, access: string | null): void;
-  saveState(): Promise<void>;
   /**
    * Ingest a record change into the processor.
    * Emits 'stream_update' event if materialized views are affected.
    * @param isOptimistic true = local mutation (increment versions), false = remote sync (keep versions)
    */
-  ingest(table: string, op: 'CREATE' | 'UPDATE' | 'DELETE', id: string, record: any): WasmStreamUpdate[];
+  ingest(table: string, op: IngestRecord['op'], id: string, record: any): WasmStreamUpdate[];
   /**
    * Register a new query plan.
    * Emits 'stream_update' with the initial result.
@@ -489,6 +555,14 @@ declare class CacheModule implements StreamUpdateReceiver {
    */
   applyRelayedIngest(tuples: CacheIngestTuple[]): void;
   lookup(recordId: string): number;
+  /**
+   * Seed the version memo from rows the circuit was primed with out of the
+   * local store, so the first post-reload sync diff does not re-download
+   * bodies the browser already has. Only rows the prime actually put into the
+   * circuit belong here: a memo entry with no circuit row would make the diff
+   * flag the id forever while nothing ever fetches it.
+   */
+  primeVersions(entries: [string, number][]): void;
   /** 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. */
   clearVersionLookups(): void;
@@ -1240,11 +1314,37 @@ declare class Sp00kySync<S extends SchemaStructure> {
   /** 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;
+  /** In-flight {@link resumeLeaderDuties}, so a second call joins the first
+   *  instead of double-draining the outbox. */
+  private leaderDutiesInFlight;
+  /** Resolves once the in-browser circuit has been primed from the local
+   *  store. Every sync diff waits on it: diffing against an empty circuit
+   *  classifies the whole working set as missing and re-downloads it. */
+  private primeGate;
+  /** The prime we last waited on. `whenPrimed` hands out one promise per
+   *  prime, so a new identity means a new prime (boot, bucket switch) ran. */
+  private settledPrime;
+  setPrimeGate(gate: () => Promise<void>): void;
+  /**
+   * Leader WIRING only, and deliberately synchronous.
+   *
+   * The coordinator publishes the leader role and tells the broker
+   * `leader-ready` the moment the store is adopted, and the broker can mint a
+   * follower's ports on the very next tick. So the follower-message handler
+   * has to be live before this returns, or a mutation forwarded in that window
+   * is dropped. Everything that can block (outbox reload, LIVE restart) moved
+   * to {@link resumeLeaderDuties}: a promotion that waits on the network holds
+   * `leader-ready` back, and a broker whose leader never reports ready serves
+   * no follower ports and re-elects no one, which wedges the whole namespace.
+   */
+  promoteToLeader(hub: LeaderSyncHub): 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>;
+   *  relay LIVE events and rollbacks to followers. 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. Runs in the
+   *  background off the promotion path, so however long it takes (or if it
+   *  never finishes) the tab is already a working leader. */
+  resumeLeaderDuties(): 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. */
@@ -2452,6 +2552,14 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    * the former to `encodeRecordId` reads `.table` off a string and throws
    * during boot.
    */
+  /**
+   * Prime the in-browser circuit from the local store. Builds the context the
+   * stream processor needs: every synced table (the app schema plus the
+   * server-written meta tables that sync down), a schema hash so a snapshot
+   * projected under another schema is not trusted, and the ids whose local
+   * `_00_rv` was bumped by an unsettled mutation.
+   */
+  private primeCircuit;
   private sessionAuthId;
   private mintSessionSalt;
 }