@spooky-sync/core 0.0.1-canary.315 → 0.0.1-canary.317

package/src/boot/boot.saga.ts

@@ -43,8 +43,9 @@ export function* boot(env: SagaEnv, opts: BootOptions): Saga<void> {
   yield fx.dispatch({ type: 'PrimeCircuit' });
 
   const restoredUserId = (yield fx.service('auth.restoreSession')) as string | null;
-  const salt = (yield fx.id('salt')) as string;
   const authId = (yield fx.service('auth.sessionAuthId')) as string | null;
+  // A reload keeps the salt its tab had, so registrations land on warm views.
+  const salt = (((yield fx.service('salt.take', authId)) as string | null) ?? (yield fx.id('salt'))) as string;
   yield fx.state.update(R.setIdentity({ sessionId: salt, userId: restoredUserId, saltUserId: authId }));
   yield fx.service('crdt.setSessionId', salt);
   if (restoredUserId) yield fx.service('ssp.setSessionAuth', authId, (yield fx.service('auth.access')) as string | null);
@@ -115,9 +116,19 @@ export function* versionsPrimed(entries: Array<readonly [string, number]>): Saga
   yield fx.state.update(R.setVersions(entries));
 }
 
-/** Hand this tab's views back to the server when the page goes away for good. */
+/**
+ * The page is going away for good: leave the salt for a reload of this tab,
+ * then hand this tab's views back to the server. The release is deferred
+ * server-side (`fn::query::leave`), so a reload that re-registers within the
+ * grace finds its views still warm.
+ */
 export function* pageHide(): Saga<void> {
-  const ids = (yield fx.state.read((s) => [...s.queries.values()].filter((e) => e.lifecycle.remote === 'registered').map((e) => e.def.id))) as unknown[];
+  const [salt, saltUserId, ids] = (yield fx.state.read((s) => [
+    s.sessionId,
+    s.saltUserId,
+    [...s.queries.values()].filter((e) => e.lifecycle.remote === 'registered').map((e) => e.def.id),
+  ])) as [string | null, string | null, unknown[]];
+  if (salt) yield fx.service('salt.leave', salt, saltUserId);
   if (ids.length > 0) yield fx.service('remote.releaseViews', ids);
 }
 

package/src/client/services.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { leaveReloadSalt, takeReloadSalt } from './services';
+
+class MemoryStorage {
+  private items = new Map<string, string>();
+  getItem(key: string): string | null {
+    return this.items.get(key) ?? null;
+  }
+  setItem(key: string, value: string): void {
+    this.items.set(key, value);
+  }
+  removeItem(key: string): void {
+    this.items.delete(key);
+  }
+}
+
+describe('reload salt', () => {
+  const g = globalThis as { sessionStorage?: unknown };
+  beforeEach(() => {
+    g.sessionStorage = new MemoryStorage();
+  });
+  afterEach(() => {
+    delete g.sessionStorage;
+  });
+
+  it('a salt left on the way out is taken once, by the same principal', () => {
+    leaveReloadSalt('s1', 'user:a');
+    expect(takeReloadSalt('user:a')).toBe('s1');
+    // Taken, not read: a tab duplicated from this page finds nothing.
+    expect(takeReloadSalt('user:a')).toBeNull();
+  });
+
+  it('another principal, or none, mints a fresh salt', () => {
+    leaveReloadSalt('s1', 'user:a');
+    expect(takeReloadSalt('user:b')).toBeNull();
+    leaveReloadSalt('s2', null);
+    expect(takeReloadSalt(null)).toBe('s2');
+    leaveReloadSalt('s3', null);
+    expect(takeReloadSalt('user:a')).toBeNull();
+  });
+
+  it('garbage or missing storage is a fresh salt, never a throw', () => {
+    (g.sessionStorage as MemoryStorage).setItem('sp00ky:salt', '{not json');
+    expect(takeReloadSalt(null)).toBeNull();
+    (g.sessionStorage as MemoryStorage).setItem('sp00ky:salt', JSON.stringify({ salt: '', authId: null }));
+    expect(takeReloadSalt(null)).toBeNull();
+    delete g.sessionStorage;
+    expect(takeReloadSalt(null)).toBeNull();
+    expect(() => leaveReloadSalt('s1', null)).not.toThrow();
+  });
+});

package/src/client/services.ts

@@ -28,6 +28,7 @@ import type { RuntimeEvent } from '../kernel/events';
 import type { ServiceCalls } from '../kernel/effects';
 import { encodeRecordId } from '../utils/index';
 import { sha256Hex } from '../utils/sha256';
+import { leaveViewsBeacon } from '../query/sql';
 import { hashOfEdge, rowOfEdge } from '../utils/edges';
 import { mintMutationId } from '../mutation/mutation-id';
 import { BucketHandle, bucketContentToBlob } from './bucket-handle';
@@ -50,6 +51,40 @@ export function writeBootBucketHint(bucketId: string): void {
   }
 }
 
+const RELOAD_SALT_KEY = 'sp00ky:salt';
+
+/**
+ * Take the salt this tab's previous page left on its way out, if it was minted
+ * for the same principal. A reload that keeps its salt re-registers every
+ * query onto the `_00_query` row it already had, which the SSP answers from
+ * the live view instead of building a new one.
+ *
+ * Taken, not read: the key is absent while a page lives, so a duplicated tab
+ * (which copies sessionStorage) mints its own salt rather than sharing this
+ * tab's remote views.
+ */
+export function takeReloadSalt(authId: string | null): string | null {
+  try {
+    if (typeof sessionStorage === 'undefined') return null;
+    const raw = sessionStorage.getItem(RELOAD_SALT_KEY);
+    if (raw === null) return null;
+    sessionStorage.removeItem(RELOAD_SALT_KEY);
+    const left = JSON.parse(raw) as { salt?: unknown; authId?: unknown };
+    return typeof left.salt === 'string' && left.salt !== '' && (left.authId ?? null) === authId ? left.salt : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Leave this page's salt for the next page in this tab; see {@link takeReloadSalt}. */
+export function leaveReloadSalt(salt: string, authId: string | null): void {
+  try {
+    if (typeof sessionStorage !== 'undefined') sessionStorage.setItem(RELOAD_SALT_KEY, JSON.stringify({ salt, authId }));
+  } catch {
+    /* private-mode storage errors: the next page mints a fresh salt */
+  }
+}
+
 // Moved to a pure module so `@spooky-sync/core/pure` and the live feed share
 // it; re-exported here for existing imports.
 export { sha256Hex };
@@ -220,6 +255,8 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
   const services: ServiceCalls = {
     'hint.read': readBootBucketHint,
     'hint.write': writeBootBucketHint,
+    'salt.take': takeReloadSalt,
+    'salt.leave': leaveReloadSalt,
     'local.connect': (bucketId) => s.local.connect(bucketId),
     'local.switchStore': (bucketId) => s.local.switchStore(bucketId),
     'local.beginSwitch': () => s.local.beginSwitch(),
@@ -260,11 +297,8 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
     'auth.consumeEndedImpersonation': () => s.auth.consumeEndedImpersonation(),
     'remote.connect': () => s.remote.connect(),
     'remote.releaseViews': (ids) => {
-      const list = ids
-        .map((id) => String(id))
-        .filter((id) => /^_00_query:[0-9a-f]{64}$/.test(id))
-        .join(', ');
-      if (list) s.remote.beaconSql(`FOR $id IN [${list}] { LET $_released = fn::query::unsubscribe($id); };`);
+      const sql = leaveViewsBeacon(ids, s.remote.sessionIds());
+      if (sql) s.remote.beaconSql(sql);
     },
     'supervisor.start': () => s.connectionSupervisor.start(),
     'tabs.start': (bucketId) => {

package/src/kernel/effects.ts

@@ -70,6 +70,8 @@ export type EffectKind = Effect['kind'];
 export interface ServiceCalls {
   'hint.read': () => string | null;
   'hint.write': (bucketId: string) => void;
+  'salt.take': (authId: string | null) => string | null;
+  'salt.leave': (salt: string, authId: string | null) => void;
   'local.connect': (bucketId: string) => Promise<void>;
   'local.switchStore': (bucketId: string) => Promise<void>;
   'local.beginSwitch': () => () => void;

package/src/modules/auth/impersonation.integration.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { createHmac } from 'node:crypto';
+import { Surreal } from 'surrealdb';
+import { AuthService } from './index';
+import { ORIGIN_TOKEN_KEY } from './impersonation';
+
+/**
+ * Impersonation start and stop against a real SurrealDB (the WASM engine) and
+ * the real SDK: record access for the admin, the `_00_impersonate` access with
+ * the same AUTHENTICATE revocation block the CLI generates, and the session
+ * functions minus the HTTP mint (the token is signed here, the way
+ * `ssp_protocol::impersonation::mint` signs it).
+ */
+
+const KEY = 'test-impersonation-key';
+const b64 = (v: string | Buffer) => Buffer.from(v).toString('base64url');
+
+function mintImpersonation(session: string, target: string, admin: string, ttlSecs = 900): string {
+  const now = Math.floor(Date.now() / 1000);
+  const header = b64(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const claims = b64(
+    JSON.stringify({
+      iss: 'SurrealDB',
+      iat: now,
+      nbf: now,
+      exp: now + ttlSecs,
+      NS: 'n',
+      DB: 'd',
+      AC: '_00_impersonate',
+      ID: target,
+      spky_imp: session,
+      spky_admin: admin,
+      spky_as_access: 'account',
+    })
+  );
+  const sig = createHmac('sha256', KEY).update(`${header}.${claims}`).digest('base64url');
+  return `${header}.${claims}.${sig}`;
+}
+
+const SCHEMA = `
+DEFINE TABLE user SCHEMALESS PERMISSIONS FOR select WHERE true FOR create, update, delete NONE;
+DEFINE ACCESS account ON DATABASE TYPE RECORD
+  SIGNIN (SELECT * FROM user WHERE email = $email AND pass = $pass)
+  DURATION FOR TOKEN 365d, FOR SESSION 365d;
+DEFINE TABLE _00_admin SCHEMALESS PERMISSIONS NONE;
+DEFINE TABLE _00_impersonation SCHEMALESS PERMISSIONS FOR select, create, update WHERE true;
+DEFINE ACCESS _00_impersonate ON DATABASE TYPE RECORD
+  WITH JWT ALGORITHM HS256 KEY '${KEY}'
+  AUTHENTICATE {
+    LET $s = (SELECT * FROM ONLY type::record($token.spky_imp));
+    IF $s = NONE OR $s.ended_at != NONE OR <string>$s.target != <string>$auth.id {
+      THROW 'Impersonation session is no longer valid.';
+    };
+    IF array::len((SELECT VALUE id FROM _00_admin WHERE user = $s.admin LIMIT 1)) = 0 {
+      THROW 'Impersonation session is no longer valid.';
+    };
+    RETURN $auth;
+  }
+  DURATION FOR TOKEN 15m, FOR SESSION 15m;
+DEFINE FUNCTION fn::_00_impersonate::start($target: string, $reason: string) {
+  IF $access = '_00_impersonate' { THROW 'Cannot start impersonation from an impersonated session.'; };
+  UPSERT _00_impersonation:s1 SET target = type::record($target), admin = $auth.id, reason = $reason, ended_at = NONE;
+  RETURN { token: $test_imp_token, session: '_00_impersonation:s1' };
+} PERMISSIONS FULL;
+DEFINE FUNCTION fn::_00_impersonate::stop($session: string) {
+  UPDATE type::record($session) SET ended_at = time::now();
+  RETURN NONE;
+} PERMISSIONS FULL;
+DEFINE FUNCTION fn::_00_impersonate::renew() {
+  IF $access != '_00_impersonate' { THROW 'Not an impersonated session.'; };
+  RETURN { token: $test_imp_token_renewed };
+} PERMISSIONS FULL;
+DEFINE FUNCTION fn::_00_impersonate::current() {
+  IF $access != '_00_impersonate' { RETURN NONE; };
+  LET $s = (SELECT * FROM ONLY type::record($token.spky_imp));
+  RETURN IF $s = NONE OR $s.ended_at != NONE { NONE } ELSE { { session: <string>$s.id } };
+} PERMISSIONS FULL;
+CREATE user:alice SET email = 'alice@x', pass = 'pw';
+CREATE user:bob SET email = 'bob@x', pass = 'pw';
+CREATE _00_admin:alice SET user = user:alice;
+`;
+
+const silentLogger = (): any => {
+  const l: any = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn(), trace: vi.fn() };
+  l.child = () => l;
+  return l;
+};
+
+describe('impersonation on the SurrealDB-WASM engine', () => {
+  let db: Surreal;
+  let adminToken: string;
+
+  beforeAll(async () => {
+    const realFetch = globalThis.fetch;
+    vi.stubGlobal('fetch', async (input: unknown, init?: RequestInit) => {
+      const url = input instanceof URL ? input : new URL(String(input));
+      if (url.protocol === 'file:') return new Response(await readFile(fileURLToPath(url)));
+      return realFetch(input as RequestInfo, init);
+    });
+    const { createWasmEngines } = await import('@surrealdb/wasm');
+    db = new Surreal({ engines: createWasmEngines() });
+    await db.connect('mem://');
+    await db.use({ namespace: 'n', database: 'd' });
+    await db.query(SCHEMA);
+    await db.query(`DEFINE PARAM $test_imp_token VALUE '${mintImpersonation('_00_impersonation:s1', 'user:bob', 'user:alice')}' PERMISSIONS FULL;`);
+    await db.query(`DEFINE PARAM $test_imp_token_renewed VALUE '${mintImpersonation('_00_impersonation:s1', 'user:bob', 'user:alice', 901)}' PERMISSIONS FULL;`);
+    const tokens = await db.signin({ access: 'account', variables: { email: 'alice@x', pass: 'pw' } });
+    adminToken = typeof tokens === 'string' ? tokens : (tokens as { access: string }).access;
+  }, 60_000);
+
+  afterAll(async () => {
+    await db?.close();
+    vi.unstubAllGlobals();
+  });
+
+  function makeAuth(opts: { failUserRead?: () => boolean; holdStop?: Promise<void> } = {}) {
+    const store = new Map<string, unknown>();
+    const persistence = {
+      get: async (k: string) => store.get(k) ?? null,
+      set: async (k: string, v: unknown) => void store.set(k, v),
+      remove: async (k: string) => void store.delete(k),
+    } as any;
+    const remote = {
+      query: async (sql: string, vars?: Record<string, unknown>) => {
+        if (sql.includes('$auth.id') && opts.failUserRead?.()) {
+          throw new Error('There was a problem with the database: the query was cancelled');
+        }
+        if (sql.includes('fn::_00_impersonate::stop') && opts.holdStop) await opts.holdStop;
+        return db.query(sql, vars);
+      },
+      setAuthToken: () => undefined,
+      getClient: () => db,
+    } as any;
+    return { auth: new AuthService({} as any, remote, persistence, silentLogger()), store };
+  }
+
+  it('stop returns to the admin', async () => {
+    const { auth, store } = makeAuth();
+    await auth.check(adminToken);
+    expect(String(auth.currentUser.id)).toBe('user:alice');
+
+    await auth.impersonate('user:bob', 'support');
+    expect(String(auth.currentUser.id)).toBe('user:bob');
+
+    await auth.stopImpersonating();
+    expect(auth.isAuthenticated).toBe(true);
+    expect(String(auth.currentUser.id)).toBe('user:alice');
+    expect(store.get('sp00ky_auth_token')).toBe(adminToken);
+    expect(store.has(ORIGIN_TOKEN_KEY)).toBe(false);
+  });
+
+  it('an explicit stop racing a server-ended stop still returns to the admin', async () => {
+    let release!: () => void;
+    const holdStop = new Promise<void>((r) => (release = r));
+    const { auth } = makeAuth({ holdStop });
+    await auth.check(adminToken);
+    await auth.impersonate('user:bob', 'support');
+
+    // The Stop button's stop is waiting on the server when the poll notices
+    // the end (or a renewal is refused). Run apart, the poll's stop returned
+    // to the admin and the button's, finding the admin token taken, signed
+    // the admin out. Now the second joins the first.
+    const explicit = auth.stopImpersonating();
+    const fromPoll = auth.stopImpersonating({ serverEnded: true });
+    release();
+    await Promise.all([explicit, fromPoll]);
+
+    expect(auth.isAuthenticated).toBe(true);
+    expect(String(auth.currentUser.id)).toBe('user:alice');
+  });
+
+  it('a failed read of the admin row on the way back keeps the admin signed in', async () => {
+    let failNext = false;
+    const { auth, store } = makeAuth({ failUserRead: () => (failNext ? ((failNext = false), true) : false) });
+    await auth.check(adminToken);
+    await auth.impersonate('user:bob', 'support');
+
+    failNext = true;
+    await auth.stopImpersonating();
+
+    expect(auth.isAuthenticated).toBe(true);
+    expect(String(auth.currentUser.id)).toBe('user:alice');
+    expect(store.get('sp00ky_auth_token')).toBe(adminToken);
+  });
+
+  it('stop after half an hour of renewals and polls returns to the admin', async () => {
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval'] });
+    try {
+      const { auth } = makeAuth();
+      await auth.check(adminToken);
+      await auth.impersonate('user:bob', 'support');
+      await vi.advanceTimersByTimeAsync(30 * 60 * 1000);
+      expect(String(auth.currentUser.id)).toBe('user:bob');
+
+      await auth.stopImpersonating();
+
+      expect(auth.isAuthenticated).toBe(true);
+      expect(String(auth.currentUser.id)).toBe('user:alice');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/modules/auth/impersonation.test.ts

@@ -260,6 +260,28 @@ describe('timers', () => {
     expect(auth.impersonation).toBeNull();
   });
 
+  it('a renewal in flight when stop begins does not put the target back on the socket', async () => {
+    const { auth, server, store } = await signedInAdmin();
+    await auth.impersonate('user:bob', 'support ticket');
+    let releaseRenew!: () => void;
+    const held = new Promise<void>((r) => (releaseRenew = r));
+    const answer = server.query.getMockImplementation()!;
+    server.query.mockImplementation(async (sql: string, vars?: Record<string, unknown>) => {
+      if (sql.includes('fn::_00_impersonate::renew')) await held;
+      return answer(sql, vars);
+    });
+
+    const renewal = auth.renewImpersonation();
+    const stop = auth.stopImpersonating();
+    releaseRenew();
+    await Promise.all([renewal, stop]);
+
+    expect(auth.currentUser.id).toBe('user:alice');
+    expect(auth.token).toBe(ADMIN);
+    expect(server.state.socketToken).toBe(ADMIN);
+    expect(store.get('sp00ky_auth_token')).toBe(ADMIN);
+  });
+
   it('keeps going through network failures on the poll', async () => {
     let calls = 0;
     const host = {

package/src/modules/auth/index.ts

@@ -103,6 +103,13 @@ export class AuthService<S extends SchemaStructure> {
   /** Target of an impersonation that just ended, until the client purges its
    *  local bucket (see `consumeEndedImpersonation`). */
   private endedImpersonationTarget: string | null = null;
+  /** The way back to the admin in flight. The Stop button, the session poll,
+   *  a refused renewal and a rejected check can all end an impersonation, and
+   *  they share this one: a second stop running beside the first found the
+   *  admin token already taken and signed the admin out. */
+  private stopping: Promise<void> | null = null;
+  /** A token renewal in flight, which a stop waits out (see `renewImpersonation`). */
+  private renewing: Promise<void> | null = null;
   private impersonationTimers = new ImpersonationTimers({
     current: () => this.impersonation,
     renew: () => this.renewImpersonation(),
@@ -272,9 +279,22 @@ export class AuthService<S extends SchemaStructure> {
    * a full sign-out rather than staying on the target.
    */
   async stopImpersonating(opts: { serverEnded?: boolean } = {}): Promise<void> {
+    if (this.stopping) return this.stopping;
+    if (!this.impersonation) return;
+    this.stopping = this.leaveImpersonation(opts).finally(() => {
+      this.stopping = null;
+    });
+    return this.stopping;
+  }
+
+  private async leaveImpersonation(opts: { serverEnded?: boolean }): Promise<void> {
+    this.impersonationTimers.clear();
+    // A renewal already sent finishes first, so it cannot put the target's
+    // token back on the socket after the admin's (it sees `stopping` and
+    // stands down).
+    await this.renewing?.catch(() => undefined);
     const info = this.impersonation;
     if (!info) return;
-    this.impersonationTimers.clear();
     if (!opts.serverEnded) {
       try {
         await this.remote.query('RETURN fn::_00_impersonate::stop($session)', { session: info.session });
@@ -314,9 +334,22 @@ export class AuthService<S extends SchemaStructure> {
 
   /** Re-sign the impersonation token before it expires. */
   async renewImpersonation(): Promise<void> {
-    if (!this.impersonation) return;
+    if (!this.impersonation || this.stopping) return;
+    const renewal = this.applyRenewal();
+    this.renewing = renewal;
+    try {
+      await renewal;
+    } finally {
+      if (this.renewing === renewal) this.renewing = null;
+    }
+  }
+
+  private async applyRenewal(): Promise<void> {
     const [renewed] = await this.remote.query<[{ token: string }]>('RETURN fn::_00_impersonate::renew()');
     if (!renewed?.token) throw new Error('Impersonation renewal returned no token.');
+    // A stop began while the server was signing: the session is being left,
+    // so a fresh token for it must not go on the socket or into storage.
+    if (this.stopping || !this.impersonation) return;
     this.remote.setAuthToken(renewed.token);
     await this.remote.getClient().authenticate(renewed.token);
     this.token = renewed.token;
@@ -399,6 +432,9 @@ export class AuthService<S extends SchemaStructure> {
     this.isLoading = true;
 
     let token: string | undefined;
+    // Set once the server has accepted the token: from then on a failure is a
+    // failure to read the user row, not a verdict on the session.
+    let accepted = false;
     try {
       token = accessToken || (await this.persistenceClient.get<string>('sp00ky_auth_token')) || undefined;
 
@@ -418,6 +454,7 @@ export class AuthService<S extends SchemaStructure> {
       // `RemoteDatabaseService.setAuthToken`).
       this.remote.setAuthToken(token);
       await this.remote.getClient().authenticate(token);
+      accepted = true;
 
       // Verify the session by fetching the full user record using $auth.id
       const result = await this.remote.query('SELECT * FROM ONLY $auth.id');
@@ -471,6 +508,17 @@ export class AuthService<S extends SchemaStructure> {
           { error, Category: 'sp00ky-client::AuthService::check' },
           'Auth check unreachable; keeping the cached session and retrying later'
         );
+      } else if (accepted && token) {
+        // The server took the token and only the read of the user row failed
+        // (a busy database, a statement error). Signing out here logged an
+        // admin out on the way back from an impersonation while the database
+        // was saturated. Keep the session on the id the token names; the row
+        // arrives with the next check or the app's own user query.
+        this.logger.warn(
+          { error, Category: 'sp00ky-client::AuthService::check' },
+          'Auth check accepted the token but could not read the user; keeping the session'
+        );
+        await this.keepAcceptedSession(token);
       } else {
         this.logger.error(
           { error, stack: (error as Error).stack, Category: 'sp00ky-client::AuthService::check' },
@@ -483,6 +531,18 @@ export class AuthService<S extends SchemaStructure> {
     }
   }
 
+  /** Hold a session the server accepted without its user row: the id comes
+   *  from the token, as on a warm boot. A token naming no user is refused. */
+  private async keepAcceptedSession(token: string): Promise<void> {
+    if (this.isAuthenticated && this.token === token && this.currentUser) return;
+    const { userId } = decodeTokenClaims(token);
+    if (!userId) {
+      await this.rejectToken(token);
+      return;
+    }
+    await this.setSession(token, { id: userId });
+  }
+
   /**
    * The server refused `token`. A refused impersonation token (stopped,
    * expired, or revoked) returns to the admin session instead of signing the

package/src/query/register.saga.test.ts

@@ -156,6 +156,24 @@ describe('registerRemote', () => {
     expect(out.dispatched).toEqual([{ type: 'FetchRows' }, { type: 'FetchRows' }, { type: 'SyncOutcome', ok: true }]);
     expect(out.emitted).toContainEqual({ type: 'query:authority', hash: 'a', known: true });
   });
+  it('a cold registration is foreground; a cached or live one is background', async () => {
+    for (const [phase, background] of [['cold', 0], ['cached', 1], ['live', 1]] as const) {
+      const seen: Array<[number, number]> = [];
+      const out = await runPure(registerRemote(env, 'a'), {
+        state: buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { phase } })]),
+        handlers: {
+          'remote.query': (_e: unknown, ctx) => {
+            const l = ctx.state.queries.get('a')!.lifecycle;
+            seen.push([l.fetchDepth, l.backgroundDepth]);
+            return happy();
+          },
+          'local.upsert': () => undefined,
+        },
+      });
+      expect(seen).toEqual([[1, background]]);
+      expect(out.state.queries.get('a')!.lifecycle).toMatchObject({ fetchDepth: 0, backgroundDepth: 0 });
+    }
+  });
   it('guards: missing entry, already registered / failed, registering without retry', async () => {
     const none = await runPure(registerRemote(env, 'zzz'), { state: buildState([]) });
     expect(none.log.filter((x) => x.kind === 'remote.query')).toHaveLength(0);

package/src/query/register.saga.ts

@@ -151,8 +151,11 @@ export function* registerRemote(env: SagaEnv, hash: QueryHash, retry = false): S
   if (!entry) return;
   const { remote } = entry.lifecycle;
   if (remote === 'registered' || remote === 'failed' || (remote === 'registering' && !retry)) return;
+  // A query that already shows rows (cached or live) only re-verifies them
+  // here: the cycle holds `fetching` but is not traffic the user waits on.
+  const background = entry.lifecycle.phase !== 'cold';
   yield fx.state.update(
-    R.compose(R.applyLifecycle(hash, { type: 'remote-registering' }), R.applyLifecycle(hash, { type: 'fetch-begin' }))
+    R.compose(R.applyLifecycle(hash, { type: 'remote-registering' }), R.applyLifecycle(hash, { type: 'fetch-begin', background }))
   );
   try {
     const table = listRefTable(env, state);
@@ -221,6 +224,6 @@ export function* registerRemote(env: SagaEnv, hash: QueryHash, retry = false): S
     }
   } finally {
     const stillThere = (yield fx.state.read((s) => s.queries.has(hash))) as boolean;
-    if (stillThere) yield fx.state.update(R.applyLifecycle(hash, { type: 'fetch-end' }));
+    if (stillThere) yield fx.state.update(R.applyLifecycle(hash, { type: 'fetch-end', background }));
   }
 }

package/src/query/sql.test.ts

@@ -50,6 +50,24 @@ describe('query sql builders (golden against the previous builders)', () => {
     expect(sql.heartbeatRowGone([{ id: a }])).toBe(false);
     expect(sql.heartbeatRowGone(undefined)).toBe(false);
   });
+  it('the pagehide beacon names the page sessions and inlines only shapes it minted', () => {
+    const a = new RecordId('_00_query', 'a'.repeat(64));
+    const b = new RecordId('_00_query', 'b'.repeat(64));
+    const s1 = 'de81a067-f4bc-4351-a2a3-1ecf06b6305a';
+    const s2 = '8A14ED5A-32B5-4B4E-973D-D2B88860932F';
+    expect(sql.leaveViewsBeacon([a, b], [s1, s2])).toBe(
+      `FOR $id IN [${a}, ${b}] { LET $_left = fn::query::leave($id, ['${s1}', '${s2}']); };`
+    );
+    const digits = new RecordId('_00_query', '1'.repeat(64));
+    expect(sql.leaveViewsBeacon([digits], [s1])).toBe(`FOR $id IN [${digits}] { LET $_left = fn::query::leave($id, ['${s1}']); };`);
+    // Anything else is dropped rather than interpolated.
+    expect(sql.leaveViewsBeacon([a, new RecordId('_00_query', "x']; DELETE user; --"), 'user:1'], [s1, "x'; DELETE user; --"])).toBe(
+      `FOR $id IN [${a}] { LET $_left = fn::query::leave($id, ['${s1}']); };`
+    );
+    // No session ids: the server could not tell this page's entries from a reload's, so send nothing.
+    expect(sql.leaveViewsBeacon([a], [])).toBeNull();
+    expect(sql.leaveViewsBeacon([], [s1])).toBeNull();
+  });
   it('upsertBodiesTx MERGEs each body inside one transaction', () => {
     const { query, vars } = sql.upsertBodiesTx([
       { id: 'thing:1', content: { a: 1 } },

package/src/query/sql.ts

@@ -76,6 +76,25 @@ export function heartbeatBatch(ids: ReadonlyArray<RecordId<string>>): { sql: str
 /** A heartbeat answer whose statement matched no row: the view was reclaimed. */
 export const heartbeatRowGone = (result: unknown): boolean => Array.isArray(result) && result.length === 0;
 
+// The SDK escapes an all-digit key as `⟨…⟩`; both forms parse back to the same id.
+const QUERY_ID = /^_00_query:(?:[0-9a-f]{64}|⟨[0-9a-f]{64}⟩)$/;
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The pagehide release: one bare statement for `beaconSql`, which has no params
+ * channel, so ids are inlined. Only shapes the client minted itself get in, a
+ * `_00_query:<sha256>` id and a UUID session id, so nothing else is ever
+ * interpolated. `null` when there is nothing the server could act on: with no
+ * session ids it could not tell this page's entries from anyone else's.
+ */
+export function leaveViewsBeacon(ids: ReadonlyArray<unknown>, sessionIds: ReadonlyArray<string>): string | null {
+  const list = ids.map((id) => String(id)).filter((id) => QUERY_ID.test(id));
+  const sids = sessionIds.filter((sid) => SESSION_ID.test(sid));
+  if (list.length === 0 || sids.length === 0) return null;
+  const sidList = sids.map((sid) => `'${sid}'`).join(', ');
+  return `FOR $id IN [${list.join(', ')}] { LET $_left = fn::query::leave($id, [${sidList}]); };`;
+}
+
 export const bodySelect = (): string => 'SELECT * FROM $ids';
 
 /** Local transaction that MERGEs many fetched bodies. */